Using complex web services in Altio

Since 2003 AltioLive has had the ability to work with SOAP web services but we only have simple examples that use primitive variables. Recent professional service projects have required the use of Web Services which use complex input and output data types so I thought I would make some notes here before a more formal document is produced.

AltioLive was developed to make integration with SOA as simple as possible, but because of the broad set of functionality available in AltioLive it is not always obvious how a certain implement a specific solution. This note will highlight how to use AltioLive to work with SOAP messages and WSDL's.

What is a complex web service?

When I mention a complex web service I mean one that takes complex XML as input and returns complex XML. This is predominant now in the Enterprise where .Net and JAX-WS object serialization makes it easy to transform objects to and from XML, resulting in deeply nested XML hierarchies.

Listed below is one approach to using a complex web service in AltioLive, the default approach is to use controls mapped to parameters in the service request - this is the default for AltioLive.

1. Generate a template of the XML structure for use by Altio Screens. The template XML can be generated using Static Data, AltioDB, or a request to a template object.
2. Map screen objects to the XML template
3. Submit the XML to a SOAP service request.
4. Map the response data to the required location

The Template

There are several options for providing the template of the complex XML. The general principal is that the application requires the XML structure that is to be passed to the Web Service, and the controls will be mapped to this XML structure.

Probably the simplest solution is to create a XML file containing the template and use this in AltioDB or as a file on the server which can be called from a HTTP request. Then create a HTTP service request to retrieve the template XML.

NOTE: Make sure the data keys are correct, as this will be a common reason why the data does not display correctly. This will be especially important for the response data.

The SOAP request

Using the WSDL wizard is probably the simplest way of creating the required SOAP request:

1. Open AltioLiveApplication Manager
2. Select WSDL from the service request types on the menu
3. Enter the URL of the WSDL that declares the SOAP service you which to use
4. Click "Retrieve Operations"
5. Select the "Operation" you want to use
6. Click "Use Selected Operation"

These steps will create a new SOAP Service Request.

Because the service request will be using complex XML structure to send and receive data then the "Parts" section of the Service Request will need to be modified. By default AltioLive will create a placeholder for the data that will be passed from the client to the request, as shown below:

<tt:create xmlns:tt='http://www.bbb.com/reports/ReportInstanceAdmin'>  
<tt:ParamData xmlns:tt='http://www.bbb.com/reports'>
    <tt:Schedule>
      <Recurrence>
        <DailyRecurrence>${client.DAILYRECURRENCE}</DailyRecurrence>
        <WeeklyRecurrence>${client.WEEKLYRECURRENCE}</WeeklyRecurrence>
        <YearlyRecurrence>${client.YEARLYRECURRENCE}</YearlyRecurrence>
        <MonthlyRecurrence>${client.MONTHLYRECURRENCE}</MonthlyRecurrence>
      </Recurrence>
    </tt:Schedule>
    <Params>
      <tt:InventoryParams>
        <ReportTitle>${client.REPORTTITLE}</ReportTitle>
        <TitleOpt>${client.TITLEOPT}</TitleOpt>
        <ReportCode>${client.REPORTCODE}</ReportCode>
        <Uid>${client.UID}</Uid>
            </Params>
    <ReportInstance>
${client.REPORTINSTANCE}</ReportInstance>
  </tt:ParamData&gt
;</tt:create>

As the XML structure will be provided through a template the XML shown above can be replaced with:

<tt:create xmlns:tt='http://www.BBB.com/reports/ReportInstanceAdmin'>${client.PARAMS}:xml</tt:create>

The parameter reference ${client.PARAMS}:xml informs AltioLive to process the parameter as a encoded XML block and will de-encode the XML when the WebService operation is called.

Processing the response

By default Altio will generate the response template using ${response.result}, this works fine for simple WebServices but as the scenario is using complex XML then the response body is the important part of the SOAP envelope and so the syntax to retrieve the message content needs to be ${response.body}, otherwise Altio will report that no XML was provided in the message.

To implement this change edit the SOAP Service Request. The "Response" tab contains a field called "Literal XML string", this defines the structure of the XML that the results of the SOAP request should be placed into. For this example use the default value but replace the ${response.result} value with ${response.body}. So that the "Literal XML string" looks like the following:

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

Client Action

The final part to using a complex web service is to implement the client logic. The first step is to retrieve the template XML, this is done through a simple request to the Service Request that will return the template XML. The second step is to implement the logic to pass the data to the SOAP Service Request that will execute the SOAP operation, the syntax of the parameter to be passed to the SOAP Service Request is shown below:

PARAMS='eval(escape(xml-string(/ReportParams/*)))'

• xml-string() – serializes the XML element into a XML string.
• escape() – performs a HTML escape of the XML string to ensure correct transmission from the client to the server.
• eval() – informs AltioLive that this is a function execution block and that the content needs processing.

The "Parameter source" property of the "Server request" action block needs to be set to STRING, otherwise AltioLive will expect to find a control called PARAMS and use the content of the control for the XML structure.

Aside from the service request execution you will need to map controls to the XML.

Conclusion

The use of a Template for working with a complex XML structure is an alternative approach to using controls to pass the required data as individual fields. The benefits of using a template is that it allows the XML block to be manipulated by many screens and allows the XML to be built up from multiple sources if necessary.

The negative aspect of using template XML might be in migrating to a different technology, and example would be moving from a SOAP message to a REST format where parameters would need to be passed rather than a complex XML structure. In my opinion if the request is very complex then a SOAP message is probably far more effective and manageable than a equivalent REST message.

The AltioLive online help provides further details of using WSDL's and SOAP Service Requests, and if you are working in a SOA environment it is worth familiarising yourself with different techniques for interacting with SOAP message.