Tutorials

Objectives of the tutorial

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

• Publishing Processes as Web Services
• Defining input/output settings via Process Parameters
• Defining hierarchical input/output structures via XML structures

The following technologies will be used:

• Databases
• XML files
• Web Services

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
• All the root nodes of the hotelManagement.xsd file must have been reversed and grouped in the project Tutorial – Common Metadata

Information: The client software used in this tutorial to illustrate SOAP calls is SOAP UI.
It is only used for the sake of example. If you want to use it, please make sure you comply with the terms of the license.
For further information, please refer to their website http://www.soapui.org.
You may use any other Web Service client to do the exercises in this tutorial.
However, if you choose another service client, although the overall methodology will remain the same, the implementation details might be different.

Environment initialization

Create the Tutorial - Publishing 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.
Create also a Processes folder which will serve to store the various Processes 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

Creating a simple Web Service

Defining the Web Service

In this section you will create a first Web Service that takes as input a state code and that sends as output the number of customers from this state.

Create a Process with the following properties:

Define a Parameter:

1. In the Palette click on the button Parameter
2. Click on the Process diagram where you want to create the Parameter
3. In the Properties view, enter stateCode in the Name field
4. Verify that the Type is set to String
5. Enter CA in the Value field

Modify the Parameter to make it an input parameter:

1. Select the Properties view
2. Select the Publication tab
3. Check the Input box

Notice that the icon changes to signal that this is an input parameter.

Warning: A Parameter cannot be used as an input/output parameter for a Web Service unless it has a default value (the Value field may not be empty)

Information: The definition of input/output parameters for a Web Service Web is optional. This means that Web Services with no input and/or output parameters can be published.

Define an output parameter with the following characteristics:

Finally, to compute the number of customers, use the action SqlToParameters. This action executes a SQL query and stores the result in a session variable:

1. In the Palette expand the Sql menu
2. Click on Sql To Parameter
3. Click on the Process diagram where you want to create the action
4. In the Properties view, enter getCustomerCount in the Name field
5. Drag-and-drop the T_ADDRESS datastore onto the action

Specify the action’s main body:

1. Select the getCustomerCount action
2. Display the Expression Editor view
3. Enter the main body of the action that specifies the parameter to be filled in and the query that will be executed

<sqlToParameters>
      <parameter name="~/customerCount" type="String">
            select count(*) from HOTEL_MANAGEMENT.T_ADDRESS
            where ADR_STATE_CODE = '${~/stateCode}$'
      </parameter>
</sqlToParameters>

The Process is now ready to be published on the Runtime as a Web Service:

1. Right-click on the diagram’s background
2. Select the Publish menu then As WebService

Invoking the Web Service Web via the HTTP/Rest Standard

Upon launching, the Runtime starts several services enabling the publication of Processes as Web Services. To invoke the Web Service, you may use:

1. The SOAP protocol
2. The HTTP/Rest standard

You can find on Runtime console and startup logs the different started services:

29/04/2020 10:31:57,115 - Runtime version: s20.0.1_20200428
29/04/2020 10:31:57,123 - Java version: 1.8.0_241 vendor: Oracle Corporation home: C:\java\1.8.0_241_jdk_64\jre
29/04/2020 10:31:57,484 - Internal Database is started: STAMBIA:42100
29/04/2020 10:31:57,513 - Internal Database Web Server is started: http://STAMBIA:42101
29/04/2020 10:32:00,225 - RMI server is started: rmi://STAMBIA:42000
29/04/2020 10:32:02,624 - Scheduler is started
29/04/2020 10:32:04,665 - SOAP Endpoint: http://STAMBIA:42200/wsi/DeliverableService?WSDL
29/04/2020 10:32:04,665 - SOAP Legacy "Non WSI-Compliant" Endpoint: http://STAMBIA:42200/nonwsi/StambiaDeliveryService?WSDL
29/04/2020 10:32:04,665 - HTTP Rest v3 - Endpoint: http://STAMBIA:42200/rest/StambiaDeliveryService/3/default/<path>
29/04/2020 10:32:04,665 - HTTP Rest v3 - UI: http://STAMBIA:42200/rest/StambiaDeliveryService/3/default?swagger-ui
29/04/2020 10:32:04,665 - HTTP Rest v3 - Definition: http://STAMBIA:42200/rest/StambiaDeliveryService/3/default?swagger2.json
29/04/2020 10:32:04,665 - HTTP Rest v2 - Endpoint: http://STAMBIA:42200/rest/StambiaDeliveryService/2/<deliveryName>
29/04/2020 10:32:04,666 - HTTP Rest v1 - Endpoint: http://STAMBIA:42200/rest/StambiaDeliveryService/1/<deliveryName>

Start by invoking the Web Service with no specified parameters:

1. Open your browser
2. Log on to the following site and replace <hostname> by your computer’s address (it appears on the console when launching a Runtime): http://<hostname>:42200/rest/StambiaDeliveryService/2/getCustomerCountByState

Your browser will then display an XML content which is the output of the Web Service:

<stbWP:getCustomerCountByStateOutput pSessionId="c0a84bcf014aedb07b3226bb5f40ddb5">
      <customerCount>11</customerCount>
</stbWP:getCustomerCountByStateOutput>

Information: the value of pSessionId in grey hereabove is unique for each execution. This means you shouldn’t take it into account when checking the results of your execution.

You may also look at the result of the execution of the Stambia Session by displaying the Sessions view and selecting the getCustomerCountByState Session. You can then check in the Variables view the value of the Session Variables associated with the Parameters by clicking on the background of the process diagram.

You will notice that:

1. the stateCode value is valued with CA. This is the default value specified on the corresponding parameter
2. the customerCount value is 11 because this is the value returned by the getCustomerCount action

You may also invoke the Web Service and give the value of stateCode as a parameter:

1. Open your browser
2. Log on to the following site and replace <hostname> by your computer’s address (it appears on the console when launching a Runtime): http://<hostname>:42200/rest/StambiaDeliveryService/2/getCustomerCountByState?stateCode=NY

The result of this invocation is then:
<stbWP:getCustomerCountByStateOutput pSessionId="c0a84bcf014aedbf2dd4fd7f27e675ae">
      <customerCount>18</customerCount>
</stbWP:getCustomerCountByStateOutput>

You can now check the Session Variable values in the new Session:

Tip: When you come back to the window of Stambia Designer, don’t forget to select the new Session in the Sessions view.

Invoking a Web Service via the SOAP protocol

Create a new SOAP Project in SOAP UI:

1. Open SOAP UI
2. Select the File menu then New SOAP Project
3. Enter Tutorial - Publishing Web Services in the Project Name field
4. In the Initial WSDL field, enter the WSDL address given in the Runtime: http://<hostname>:42200/wsi/DeliverableService?WSDL (remember to replace <hostname> by your computer’s name)
5. Verify that the Create Requests box is checked
6. Click OK

You can now invoke the Web Service:

1. Deploy the node Tutorial – Publishing Web Services
2. Deploy the node DeliverableBinding
3. Deploy the node getCustomerCountByState
4. Double-click on the node Request 1

You will obtain a default SOAP request that you can edit to specify the input value of the stateCode parameter:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:wrap="http://stambia.com/document/literal/wrapped">
      <soapenv:Header/>
      <soapenv:Body>
            <wrap:getCustomerCountByStateInput pAsynchronous="false" pSessionId="?" pParentSessionId="?" pLogLevel="?" pSessionName="?">
                  <!--Optional:-->
                  <stateCode>NY</stateCode>
            </wrap:getCustomerCountByStateInput>
      </soapenv:Body>
</soapenv:Envelope>

Click on the button to submit your request.

You then get the result of the execution:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
      <SOAP-ENV:Body xmlns:stbPS="http://stambia.com/xsd/standard" xmlns:stbXP="http://stambia.com/xsd/parameters">
            <stbWP:getCustomerCountByStateOutput pSessionId="c0a84bcf014aee1d471a870a1707eb57" xmlns:stbWP="http://stambia.com/document/literal/wrapped">
                  <customerCount>18</customerCount>
            </stbWP:getCustomerCountByStateOutput>
      </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Creating a Web Service with a one-level input/output structure

Defining the Web Service

In this section, you will create a Web Service the input of which is a customer’s number, and the output of which is the basic information about this customer.

Creating the Mapping

Create a Mapping with the following properties:

The transformation business rules are:

The join business rules are:

Tip: If on your workspace, you’ve got the elements created during the Tutorial Working with XML files, you can create this Mapping by making a copy of the Load customerSummary Mapping. Locate this Mapping in the Project Explorer, then right-click on it and select Copy, then right-click on the folder Tutorial – Publishing Web Services/Mappings and select Paste.

Add a filter on the T_CUSTOMER Datastore using a parameter which will be created later by the Process that will use this Mapping:

1. Drag-and-drop the CUS_ID column onto the background of the diagram
2. Modify the expression in the Expression Editor in order to use a customerId parameter found in the main Process of the Session

T_CUSTOMER.CUS_ID = ${~/customerId}$

Creating the Process

Create a new Process with the following characteristics:

Define an input parameter with the following characteristics:

Reminder: For a parameter to be taken into account in a Web Service, it must be defined with a default value in the Process.

This is the parameter that will be used in the Filter of the Mapping with the expression ${~/customerId}$

Now define a Web Service structure:

1. Drag-and-drop the customerSummary element into the Process

Then define this element as an output structure:

1. Select the customerSummary element
2. In the Properties view, display the Publication tab
3. Check the Output box

Information: You can also define the Web Service input structures in the same way and checking the Input box.

This means that the XML file corresponding to the customerSummary root element will be returned by the Web Service as an output structure. Now, the Mapping created hereabove serves to load this XML file. So this Mapping must be added to the Process:

1. Drag-and-drop the getCustomerSummary Mapping into the Process
2. Publish this Process as a Web Service.

You now have got a Web Service that:

• Takes as input a customerId Parameter
• Executes a Mapping using this parameter and loading an XML file
• Sends back the contents of this XML file as an output structure

Invoking the Web Service and analyzing the result of the execution

Invoke the Web Service while specifying a customer number:

1. Open your browser
2. Log on to the following site and replace <hostname> by your computer’s address (it appears on the console when launching a Runtime): http://<hostname>:42200/rest/StambiaDeliveryService/2/getCustomerSummary?customerId=1

Your browser will then display an XML content that represents the output of the Web Service:

<stbWP:getCustomerSummaryOutput pSessionId="c0a84bcf014af1f336065f374fc64b65">
      <mgt:customerSummary>
            <customer birthDate="1975-02-15T00:00:00+01:00" company="" customerId="1" firstName="Jason" lastName="GIBBS " title="Mister" titleCode="Mr "/>
      </mgt:customerSummary>
</stbWP:getCustomerSummaryOutput>

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

Information: You can also invoke this Web Service via the SOAP protocol.

Information: If you haven’t executed the Tutorial – Working with XML files on these demonstration databases, the birthDate attribute will not appear in the output structure, because its initial value in the source base is NULL. As a consequence, the SUM(XML_NB_ATTRIBUTES) statistic will be 6 and not 7.

Creating a Web Service with a complex input/output structure

Defining the Web Service

In this section, you will create a Web Service the input of which is a customer’s number and the output of which is the detailed information about this customer.

Creating the Mapping

Create a Mapping with the following properties:

Tip: If in your workspace, you have got the elements created during the Tutorial Working with XML files, you can create this Mapping by making a copy of the Load customerDetails Mapping. Locate this Mapping in the Project Explorer, then right-click on it and select Copy, then right-click on the Tutorial – Publishing Web Services/Mappings folder and select Paste. You will have to modify the Template parameters so that Stambia uses the default location when loading the XML file and so that the data may then be published into the Web Service. Click on the Integration Template of the XML file then, in the Properties view, click on the Out File Name link in order to reinitialize this parameter to its default value.

The transformation business rules are:

The join business rules are:

Add a filter on the T_CUSTOMER Datastore using an input parameter named customerId:

T_CUSTOMER.CUS_ID = ${~/customerId}$

Creating the Process

Create a new Process with the following characteristics:

Define an input parameter with the following characteristics:

Now define the Web Service’s output structure based on the hotelManagement root element.

Add the getCustomerDetails Mapping to the Process.

Finally, publish the Process as a Web Service.

Invoking the Web Service and analyzing the result of the execution

Invoke the Web Service while specifying a customer number:

1. Open your browser
2. Log on to the following site and replace <hostname> by your computer’s address (it appears on the console when launching a Runtime): http://<hostname>:42200/rest/StambiaDeliveryService/2/getCustomerDetails?customerId=1

Your browser will then display an XML content that represents the output of the Web Service:

<stbWP:getCustomerDetailsOutput pSessionId="c0a84bcf014af2069688c8a1021dc5bb">
      <mgt:hotelManagement>
            <customer company="" customerId="1" firstName="Jason" lastName="GIBBS " title="Mister" titleCode="Mr ">
                  <address addressId="1" city="BOSTON" line1="610 Beacon St" line2="" line3="" line4="" stateCode="MA" zipCode="02115"/>
                  <phone phoneId="1" phoneNumber="(413)454-5663 " phoneType="Home" phoneTypeCode="HOM "/>
                  <phone phoneId="2" phoneNumber="(413)442-5252 " phoneType="VoIP" phoneTypeCode="SIP "/>
                  <phone phoneId="3" phoneNumber="(413)442-5250 " phoneType="Office" phoneTypeCode="OFF "/>
                  <email emailAddress="jgibbs@hotmail.com" emailId="1" emailType="home"/>
            </customer>
      </mgt:hotelManagement>
</stbWP:getCustomerDetailsOutput>