Tutorials

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:

• Creating and reversing WSDL Metadata (Web Services Definition Language)
• Creating Mappings that invoke Web Services
• Creating Mappings to use the result of the Web Service invocation

The following technologies will be used:

• Databases
• Web Services and WSDL

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:

• The three Metadata files of the Tutorial: fundamentals of Stambia must have been properly reversed and be grouped in the project Tutorial – Common Metadata
• The templates must have been imported into the global project

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 close the Designer and Runtime, and then delete the <Designer Installation>/stambiaRuntime/samples folder.
At the next Designer restart, it will be re-created with default settings and data.

Fetching the Templates

Templates are provided by Stambia on its community website: www.stambia.org

1. With your web browser, connect to the following site www.stambia.org using the connection information provided by Stambia.
2. Select the Download menu, then Templates
3. Click on the Download button in the Wsdl tab
4. Your browser will enable you to download a file named templates.wsdl.YYYY-MM-DD.zip (where YYYY-MM-DD represents the date on which this version of the Templates was last updated)
5. Save this file in a work folder (on your desktop for example)

Information: If you encounter problems during the connection, please contact our global Technical Support Center: www.stambia.org/di/support.

Importing Templates

To import the ZIP format archive containing the Templates:

1. Come back to the Stambia Designer window.
2. Go to the Project Explorer view.
3. Right-click on the Project global and select Import... in the contextual menu.
4. Select General as Import source, then Archive File.
5. Now, click on Next
6. Click on Browse (at the top of the window)
7. Browse until you find the zip file with the Templates and select it.
8. Make sure you import the root of the archive (the / box must be checked)
9. Check that the import destination is the Project global
10. Click on Finish

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:

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

The transformation business rules are:

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:

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:

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:

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.