Setting the SOAP Service Functions
 

Description

A SOAP Service Function configures the SOAP Service Request, and how the SOAP service response is handled, including the generation of data to return to the client.

The response from the SOAP service is used to configure the XML data returned from the SOAP service. This works in a similar way to how the services are invoked: when a client invokes a service, the combination of data from the client and the service definition is used to make the service call. Similarly, the combination of the SOAP response message and the service definition is used to create the data to return from the service.

SOAP services can be invoked by a client, for initial data, and to obtain data to feed a Datapool.

Rather than manually enter the data to configure a SOAP service, this information can be automatically extracted from a Web Service Definition Language (WSDL) file that describes the target SOAP service. The WSDL file must include a SOAP binding for the service definition to be invoked. See Using the WSDL Wizard.

For more information:  on how to set and use SOAP Service Functions, you can run the Web Services Techlet. You can find it from AltioLive Studio Explorer, under the Sample and Techlets node. Just expand the Web Sevices folder and select the view.xml file under it. Click the Run icon and go through the Techlet.

Creating a new SOAP Service Function

1. From the Application Manager do one of the following:

2. Click on the New SOAP service button in the toolbar.

3. Click on the Edit|New SOAP service menu item.

4. Right-click on the Services node in the Application Explorer window and select New SOAP service in the context menu.

A SOAP Service Function is added to the list of Services with the default name of SOAPSERVICE1. The following Service details window will open:

The Request Tab

The Request tab configures the parameters required for a remote web service operation.

1. In the Service Name field enter the name by which the Service Function is referenced.

2. In the Location field enter the URL of the server hosting the webservice.

3. The SOAP Action Header is normally blank but it can be used by the host server to direct the SOAP webservice header to the implementation. If omitted, the default setting is an empty string.

4. When invoking a HTTP service that returns Set-Cookie or Set-Cookie2 header Presentation Server saves the Cookie information so that when subsequent calls to services of same domain and path, this cookie information can be sent back. From the Server side cookie scope drop-down menu choose how the Presentation Server stores the cookie information and how cookie information will be shared among services. Choose one of the following option:

5. Session: Cookie is stored per HTTP Session and is shared among all services with SESSION cookie scope within same HTTP session.

6. Application: Cookie is stored per Altio Application and is shared among all services with APP cookie scope in the same application.

7. Presentation Server: Cookie is stored at Presentation Server and is shared among all services with PS cookie scope.

For more information: see Server Side Cookie Handling.

5. Tick the Send client cookie option if you want the Presentation Server to pass on cookie(s) from client browser to backend service.

6. You can set the Request headers to supply more SOAP headers to the request, for the purpose of routing the SOAP packet:

7. Click on the Add button.

8. Tick the Must Understand box if you want the target actor has to understand this header. This attribute is optional, the default setting is set to false.

9. In the Actor cell enter, The URL location of a target SOAP actor. The purpose of an actor is to redirect the SOAP packet to another location on its route to the webservice server. This attribute is optional.

10. In the Value cell, enter string representing well-formed XML. This is a required part of a SOAP header.

7. In the Binding style box choose whether:

8. RPC: stands for Remote Procedure Call. A method is being invoked, and each 'Part' being sent is a method parameter.

9. DOC: stands for Document. Each 'Part' being sent is an XML fragment. Presentation Server can build and send data array in the XML fragment.

Please note: One of these should be set according to the request structure expected by the SOAP web service.

8. If RPC parameter is selected in Namespace field, enter the namespace of the request element. In Operation field, enter the name of the method invoked.

9. In the Parts table you can set a block of information to be sent to the web service. There can be zero or more parts.

10. Click on the Add button.

11. In the Name cell, enter the name of the part.

12. In the Type drop-down menu, choose the type of the value that is being sent. When you use DOCUMENT binding, only LITERAL type may be used.

13. In the Value cell enter the value to use. It will normally contain references to the client data. If the type is LITERAL, then this field must evaluate to well-formed XML.

Example:

AltioLive SOAP service extends AltioLive standard property reference to handle data array. User can use something like ${client.VAL}:Int[] to indicate that an array of <Int> nodes is expected. If "1:2:3:4" is sent from client as the value of VAL, the Presentation Server will parse the string to build XML fragment like the following:

     <Int>1</Int>
     <Int>2</Int>
     <Int>3</Int>
     <Int>4</Int>

The default delimiter is :, but you can change it by specifying a <ARRAY_ITEM_SEPARATOR VALUE="*"/> node under <INIT> node. Setting this value is currently not supported in Presentation Server Administration Tool. You can only do this by manually editing the server configuration file called altioserver.xml.

AltioLive SOAP service also supports ${client.VAL} xml notation. This indicates that the value of ${client.VAL} shall be treated as XML block and shall not be escaped.

The Response Tab

The Response tab configures how returned values from a remote web service operation are processed. It is intended to be very flexible, with full control over the data that is returned to the client. In particular, if XML data is to be returned, then this can be formed from a combination of literal XML with elements from the SOAP response.

Setting the Aliases table

• Name: Enter here the name of this alias.

• XPath statement to run against response envelope: Enter here the XPath to obtain the data represented by this alias. An alias is useful in creating the XML.

Setting the "When service is used for initial data request" box

Custom Initial Timestamp:

Please note: This only applies to XML Service Functions.

Check this box if you want the Timestamp to be extracted from a customized location. If this option is selected you can set the Element and Attribute for locating timestamp information. By default Timestamp are extracted from a Timestamp Attribute on the root element of the XML returned by the Service.

System Generated Timestamp

Please note: This option is useful when the return data doesn't contain Timestamp information. However, if you use MASTER-MASTER cluster configuration, data might be lost in failover situation, because the timestamp value for a data block can be different on two Presentation Servers.

Please also note: APS uses Java currentTimeMillis() to set the timestamp. Although its precision is down to 1 ms, the problem is that default timing systems on the native platforms are, in general, of low resolution. The currentTimeMillis is updated every 10ms ~ 16 ms. Therefore it is possible that 2 updates arrive in order but end up in the same millisecond.

Check this box if you want the Presentation Server to use system clock for the Timestamp value.

Element (XPath query)

Set this field to an XPath statement pointing to the element containing Timestamp information. By default the Presentation Server continues to find Timestamp information from root element. If more than one element matches, only the first element is used.

Attribute

Specify the attribute name containing the Timestamp info or TEXT() to indicate that the element's text contains the timestamp. By default the Presentation Server finds Timestamp information from Timestamp default attribute.

Type

Specify whether the Timestamp field is to be read as a Date/Time or as an Integer. By default the Type is set to Integer.

Format

Specify the Format used to parse the Timestamp from the specified Element and Attribute. For a Date/Time this should be a format recognized by java.text.SimpleDateFormat. For an Integer this should be a format recognized by java.text.DecimalFormat. By default if the Type is set to Integer then the Timestamp Attribute is read as an Integer.

Setting the Returned Data box

Output Type

Choose in the drop-down menu between XML or EMPTY. If this is set to XML, then Literal XML String is evaluated to construct the XML to return.

Literal XML String

The Default setting displays <SOAP>${response.value}</SOAP>. This constructs a well-formed block of XML, which represents the returned results. It can contain a generic string with property references. See the SOAP Response Processing section below.

Remove Namespace

Check this box to remove namespace information from result xml.

Transformation XSL file

Please note: The XSL file could potentially add or remove Elements, Attributes, change names of Elements or Attributes. Using this feature requires that a JAXP compliant XSLT library is available on the servlet engine's CLASSPATH, for example Xalan, Apache's open source XSLT library (xalan.jar).

1. Place your XSL file in the XSL sub-directory (under the Application root directory) as the Transformation XSL file drop-down menu displays only the XSL files in that directory.

2. Specify the XSL file you want to use to transform return XML data before it is sent to the client.

Create new transformer

Check this box to create a new transformer instance every time it does the transformation. By default it is set to false.

The SOAP Response Processing

There are three properties available for SOAP response processing:

• ${response.body} This property is always available. It maps onto the first child element of the response body element.

• ${response.alias.xxx} (when xxx is the name of the alias) is an XPath statement referred to by name. The root of the XPath statement is the envelope element of the SOAP response, so any information contained by the SOAP response is available via this mechanism.

• ${response.result} Here the result is configured according to its expected result type as described in the attribute 'a:type'. As the result could contain invalid XML, ${response.result} can be wrapped in CDATA which prevents the string from being parsed. If SOAP result type is not supported simple data type of integer, float, long, double, String, etc, using ${response.result} might result in XML parsing error. If this is the case, you shall change Literal XML String to use ${response.body} of ${response.alias.xxx} instead.

Example 1: Body

Using ${response.body} in the FromEuro example, the Literal XML string could be:

<DATA><SOAP><FromEuro>${response.body}</FromEuro></SOAP></DATA>

Test Values of 'DEM' and 100 would return:

<DATA>
    <SOAP>
      <FromEuro>
        <a:FromEuroResponse xmlns:a='urn:Euro-IEuro'>
          <return b:type='xsd:double' xmlns:b='http://www.w3.org/2001/XMLSchema-instance'>195.583</return>
        </a:FromEuroResponse>
      </FromEuro>
    </SOAP>
</DATA>

Example 2: Alias

Using ${response.alias.xxx} in the FromEuro example, the Literal XML string could be:

<DATA><SOAP><FromEuro>${response.alias.XXX}</FromEuro></SOAP></DATA>

With the Aliases configured as:

Test Values of DEM and 100 would return:

<DATA>
    <SOAP>
      <FromEuro>
        <return a:type='xsd:double' xmlns:a='http://www.w3.org/2001/XMLSchema-instance'>195.583</return>
      </FromEuro>
    </SOAP>
</DATA>

Example 3: Result

Using ${response.result} in the FromEuro example, the Literal XML string could be:

<DATA><SOAP><FromEuro><![CDATA[${response.result}]]></FromEuro></SOAP></DATA>

Test Values of DEM and 100 would return:

<DATA>
    <SOAP>
      <FromEuro>195.583</FromEuro>
    </SOAP>
</DATA>

Usage notes:

If the result of the service is not what was expected, a good way to start in debugging is to define an alias which picks up the Envelope element of the SOAP response. Thus define an alias, say called ENV, with the value of "/Envelope". Then in the response box, delete all content and simply type in ${response.alias.ENV}. The result when the service is run again will then be the returned SOAP envelope, and you can gradually shape the result from there to be in a suitable form.

The Acknowledgement Tab

The Acknowledgement tab configures messages that can be displayed on success or failure of the remote web service Operation.

1. From the On success Source drop-down menu, specify the success message to send to the AltioLive client when a service succeed. Choose one of the following:

2. NONE: no message will be sent to the client.

3. DEFINE: will return the value entered in the Text field.

2. If you have selected DEFINE, in the Text field, enter the message to send when the service succeed.

3. From the On failure Source drop-down menu, specify the fail message to send to the AltioLive client when a service failed. Choose one of the following:

4. NONE: no message will be sent to the client.

5. DEFINE: will return the value entered in the Text field.

4. If you have selected DEFINE, in the Text field, enter the message to send when the service succeed.

The Test Tab

The Test tab allows a SOAP Service to be tested by sending parameter values to a remote web service Operation. Any return values are displayed.

In the Test Properties table:

1. In the Name cell enter the name of parameters being used.

2. In the Test value cell enter a value to test the Service SOAP.

3. Click the Test button. This displays the results of executing a call to the SOAP web Service using the parameters in the Test Properties table. This is the XML that would be returned to the client.

4. If a WARNING message "No Datakey is defined for element NAME_ELEMENT is displayed, you can click on the Extract Datakeys button in order to create a datakey for this element.

For more information: See the Setting up Datakeys section.

See also:

Using the WSDL Wizard to add SOAP Service Function, Setting up Service Functions.