Objectives of the tutorial

The objective of this tutorial is to get to know the functionalities of Stambia regarding Web Service invocations.
We will study the following points:

The following technologies will be used:

Prerequisites

This tutorial has been designed to be done after the Tutorial: Working with XML Files. The notions learned in this tutorial are supposed to be known and the environment we will use is the same. Please pay attention to the following points:


Environment initialization

Create the Tutorial - Invoking Web Services Project, which will serve to store all the elements of this tutorial.

Inside this project, create a Mappings folder which will serve to store the various Mappings that you will be creating.

Finally, start the demonstration environment:

  1. Go to the Runtime view
  2. Click on Environment
  3. Click on Start local Runtime and Start demo Database
  4. Click on OK to close this window
  5. In the Runtime view, check the Connect box and verify that Refresh Diagram is checked

Tip:
If you stop the demo environment or if you stop your machine, do not forget to restart the demo environment before you resume work on the tutorial at the place where you stopped.

Important:
Be careful to stop properly the demo databases when closing the environment, with the use of the Stop demo Databases button.
Closing them violently may lead to the instability of the demo databases.
If you are facing instabilities with it, if the connection is running indefinitely, or if you dropped or remove by mistake tables or data, you can at any time re-initialize the demo environment.
For this refer to the following article:
Reset tutorials demo databases


Reversing the geocoding Web Service

The handling of Web Services in Stambia will use the same principles that guide the handling of databases or XML files. Metadata are used to declare their structure, then the details of their structure are fetched by a Reverse engineering.

Start by creating the Metadata file which will describe the Web Service:

  1. Right-click on the Tutorial – Common Metadata Project
  2. Select New then Metadata
  3. In the list of technologies, select Wsdl then click on Next
  4. Enter the name of the Metadata file: Geocoder
  5. Click on Finish

The Web Service Reverse engineering assistant automatically opens:

  1. In the Name field, enter the value: geocoder
  2. In the Url field, enter the value: http://geocoder.stambia.org:62220/geocoder?wsdl
  3. You can now click on Reverse then on Finish

Stambia then does the Reverse engineering based on the structure defined in the WSDL found at the address: http://geocoder.stambia.org:62220/geocoder?wsdl. This structure will be represented as a tree in the Metadata file.

Save this Metadata file.


Invoking the geocoding Web Service

In the Web Service you have just reversed, a specific Operation allows you to find the latitude and the longitude of the address entered as a parameter with a string format.

The first step consists in creating a Mapping which will invoke the Web Service while giving it the parameters that it requires. The data returned by the Web Service can then be used as a source for a second Mapping.

Creating the Mapping

Create a Mapping with the following properties:

Property Value
Parent folder Tutorial – Invoking Web Services/Mappings
Mapping name Invoke Geocoder
Target Datastore geocode_address
Source Datastore T_ADDRESS

The target Datastore here is the operation geocode_address which is one of the objects previously reversed.

The transformation business rules are:

Target column Business rule Characteristics
geocode_address T_ADDRESS.ADR_ID Source I/U Functional key
geocode_address/Input
geocode_address/Input/parameters
geocode_address/Input/geocode_address
geocode_address/Input/geocode_address/address T_ADDRESS.ADR_LINE1 + case when T_ADDRESS.ADR_LINE2 is not null then ', ' + T_ADDRESS.ADR_LINE2 end + case when T_ADDRESS.ADR_LINE3 is not null then ', ' + T_ADDRESS.ADR_LINE3 end + case when T_ADDRESS.ADR_LINE4 is not null then ', ' + T_ADDRESS.ADR_LINE4 end + T_ADDRESS.ADR_CITY + ' ' + T_ADDRESS.ADR_STATE_CODE + ' ' + T_ADDRESS.ADR_ZIP_CODE Source I/U
geocode_address/Output
geocode_address/StandardFault

Information: In the invocation, only the Input element needs to be loaded. The Output and StandardFault elements form the Web Service’s answer and will only be used in a second step.

Important: As for an XML Mapping, the functional key shows the values on which Stambia will iterate to invoke the Web Service. In this Mapping, the Web Service will be invoked for each value of T_ADDRESS.ADR_ID.

You can now save and execute this Mapping.

Analyzing the result of the execution

Go to the Statistic view to check the statistics of the execution:

Name Value
SUM(OUT_NB_FILES) 1
SUM(SQL_NB_ROWS) 90
SUM(WSDL_NB_DONE) 26
SUM(WSDL_NB_ERROR) 64
SUM(XML_NB_ATTRIBUTES) 12707
SUM(XML_NB_ELEMENTS) 2253

These statistics show in particular that 90 lines were returned by the source data (SQL_NB_ROWS) and that they resulted in 90 invocations of the Web Service (WSDL_NB_DONE and WSDL_NB_ERROR).
You can notice that 26 invocations are successful (the address is found by the web service) and 64 in error (the address is not found).


Using the data returned by the Web Service

Modifying the Mapping

Modify the previous Mapping by adding once more T_ADDRESS in order to update it with the data sent in from the Web Service.

The transformation business rules for T_ADDRESS_2 are:

Target column Business rule Characteristics
ADR_ID geocode_address.geocode_address Source I/U Functional key
CUS_ID
ADR_LINE1
ADR_LINE2
ADR_LINE3
ADR_LINE4
ADR_ZIP_CODE
ADR_CITY
ADR_STATE_CODE
ADR_LAT geocode_address.geocode_address/Output/parameters/geocode_addressResponse/return/latitude Source I/U
ADR_LON geocode_address.geocode_address/Output/parameters/geocode_addressResponse/return/longitude Source I/U

Information: The value geocode_address.geocode_address comes from the invocation and not from the result returned by the Web Service. Indeed, Stambia keeps each parameter sent during the invocation of a Web Service and makes them available during reading time. This means it becomes very easy to have an expression for the Mapping’s functional key since the value used in the invocation Mapping for geocode_address.geocode_address was T_ADDRESS.ADR_ID. So it is logical to use again this value to load the functional key ADR_ID.

You can now save and execute this Mapping.

Analyzing the result of the execution

Go to the Statistic view to check the statistics of the execution:

Name Value
SUM(IN_NB_FILES) 1
SUM(OUT_NB_FILES) 1
SUM(SQL_NB_ROWS) 569
SUM(SQL_STAT_INSERT) 0
SUM(SQL_STAT_UPDATE) 26
SUM(WSDL_NB_DONE) 26
SUM(WSDL_NB_ERROR) 64
SUM(XML_NB_ATTRIBUTES) 17198
SUM(XML_NB_ELEMENTS) 3 992

You can also consult the content of the T_ADDRESS table in order to check that certain addresses were properly geocoded: the fields ADR_LAT and ADR_LON are filled.