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:

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:

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:

Property Value
Parent folder Tutorial – Publishing Web Services/Processes
Process name getCustomerCountByState

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:

Name customerCount
Type String
Value 0
Publication Output

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:

customerCount 18
stateCode NY

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:

Property Value
Parent folder Tutorial – Publishing Web Services/Mappings
Name of the Mapping getCustomerSummary
Target Datastore customerSummary
Source Datastore T_CUSTOMER, T_TITLE

The transformation business rules are:

Target column Business rule Characteristics
customerSummary Functional key
customerSummary/customer T_CUSTOMER.CUS_ID Source I/U Functional key
customerSummary/customer/@birthDate T_CUSTOMER.CUS_BIRTH_DATE Source I/U
customerSummary/customer/@company T_CUSTOMER.CUS_COMPANY Source I/U
customerSummary/customer/@customerId T_CUSTOMER.CUS_ID Source I/U
customerSummary/customer/@firstName T_CUSTOMER.CUS_FIRST_NAME Source I/U
customerSummary/customer/@lastName T_CUSTOMER.CUS_LAST_NAME Source I/U
customerSummary/customer/@title T_TITLE.TIT_NAME Source I/U
customerSummary/customer/@titleCode T_CUSTOMER.TIT_CODE Source I/U

The join business rules are:

First Datastore Second Datastore Business rule Characteristics
T_CUSTOMER T_TITLE T_CUSTOMER.TIT_CODE=T_TITLE.TIT_CODE Source Inner

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:

Property Value
Parent folder Tutorial – Publishing Web Services/Processes
Name of the Process getCustomerSummary

Define an input parameter with the following characteristics:

Name customerId
Type String
Value -1
Publication Input

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:

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:

Name Value
SUM(OUT_NB_FILES) 1
SUM(SQL_NB_ROWS) 1
SUM(XML_NB_ATTRIBUTES) 7
SUM(XML_NB_ELEMENTS) 2

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:

Property Value
Parent folder Tutorial – Publishing Web Services/Mappings
Name of the Mapping getCustomerDetails
Target Datastore hotelManagement
Source Datastore T_CUSTOMER, T_TITLE, T_PHONE, T_PHONE_TYPE, T_ADDRESS, T_EMAIL

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:

Target column Business rule Characteristics
hotelManagement Functional key
hotelManagement/customer T_CUSTOMER.CUS_ID Source I/U Functional key
hotelManagement/customer/@birthDate T_CUSTOMER.CUS_BIRTH_DATE Source I/U
hotelManagement/customer/@company T_CUSTOMER.CUS_COMPANY Source I/U
hotelManagement/customer/@customerId T_CUSTOMER.CUS_ID Source I/U
hotelManagement/customer/@firstName T_CUSTOMER.CUS_FIRST_NAME Source I/U
hotelManagement/customer/@lastName T_CUSTOMER.CUS_LAST_NAME Source I/U
hotelManagement/customer/@title T_TITLE.TIT_NAME Source I/U
hotelManagement/customer/@titleCode T_TITLE.TIT_CODE Source I/U
hotelManagement/customer/address T_ADDRESS.ADR_ID Source I/U Functional key
hotelManagement/customer/address/@addressId T_ADDRESS.ADR_ID Source I/U
hotelManagement/customer/address/@city T_ADDRESS.ADR_CITY Source I/U
hotelManagement/customer/address/@line1 T_ADDRESS.ADR_LINE1 Source I/U
hotelManagement/customer/address/@line2 T_ADDRESS.ADR_LINE2 Source I/U
hotelManagement/customer/address/@line3 T_ADDRESS.ADR_LINE3 Source I/U
hotelManagement/customer/address/@line4 T_ADDRESS.ADR_LINE4 Source I/U
hotelManagement/customer/address/@stateCode T_ADDRESS.ADR_STATE_CODE Source I/U
hotelManagement/customer/address/@zipCode T_ADDRESS.ADR_ZIP_CODE Source I/U
hotelManagement/customer/phone T_PHONE.PHO_ID Source I/U Functional key
hotelManagement/customer/phone/@phoneId T_PHONE.PHO_ID Source I/U
hotelManagement/customer/phone/@phoneNumber T_PHONE.PHO_NUMBER Source I/U
hotelManagement/customer/phone/@phoneType T_PHONE_TYPE.PHT_NAME Source I/U
hotelManagement/customer/phone/@phoneTypeCode T_PHONE_TYPE.PHT_CODE Source I/U
hotelManagement/customer/phone/@phoningAllowed T_PHONE.PHO_PHONING_ALLOWED Source I/U
hotelManagement/customer/email T_EMAIL.EML_ID Source I/U Functional key
hotelManagement/customer/email/@emailAddress T_EMAIL.EML_ADDRESS Source I/U
hotelManagement/customer/email/@emailId T_EMAIL.EML_ID Source I/U
hotelManagement/customer/email/@emailType T_EMAIL.EML_TYPE Source I/U
hotelManagement/customer/email/@mailingAllowed T_EMAIL.EML_MAILING_ALLOWED Source I/U

The join business rules are:

First Datastore Second Datastore Business rule Characteristics
T_CUSTOMER T_TITLE T_CUSTOMER.TIT_CODE=T_TITLE.TIT_CODE Source outer join Lead Table: T_CUSTOMER
T_CUSTOMER T_EMAIL T_CUSTOMER.CUS_ID=T_EMAIL.CUS_ID Source outer join Lead Table: T_CUSTOMER
T_CUSTOMER T_ADDRESS T_CUSTOMER.CUS_ID=T_ADDRESS.CUS_ID Source outer join Lead Table: T_CUSTOMER
T_CUSTOMER T_PHONE T_CUSTOMER.CUS_ID=T_PHONE.CUS_ID Source outer join Lead Table: T_CUSTOMER
T_PHONE T_PHONE_TYPE T_PHONE.PHT_CODE=T_PHONE_TYPE.PHT_CODE Source outer join Lead Table: T_PHONE

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:

Property Value
Parent folder Tutorial – Publishing Web Services/Processes
Name of the Process getCustomerDetails

Define an input parameter with the following characteristics:

Name customerId
Type String
Value -1
Publication Input

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>