3 Initiating Transformations Using the SOAP API

All SOAP requests sent to, and all SOAP responses sent by Transformation Server are UTF-8 encoded UNICODE. To use Transformation Server in a SOAP application, the application should send the TransformRequest message defined in the transform.wsdl.

Three other .wsdl files are included with Transformation Server:

transform_net.wsdl should be used by those working with Microsoft's DevStudio .NET development tools.
transform_net_2005.wdsl should be used by those working with Visual Studio 2005 or Visual Studio 2008.
transform_axis.wsdl should be used by those working with Apache.org's Axis development tools.

Microsoft's tool sproxy does not support the declaration of SOAP arrays, which are part of the Transformation Server SOAP interface. As a result, none of the .wsdl files provided with Transformation Server can be successfully interpreted by sproxy.

This chapter includes the following sections:

Section 3.1, "TransformRequest"
Section 3.2, "TransformationResponse"
Section 3.3, "Transformation Server's HTTP GET/POST Interface"

3.1 TransformRequest

Initiates a transformation based on criteria contained within the message.

Prototype

<message name="TransformRequest">
   <part name="source" type="ts:IOSpec"/>
   <part name="sink" type="ts:IOSpec"/>
   <part name="outputFormat" type="xsd:string"/>
   <part name="optionSet" type="xsd:string"/>
   <part name="options" type="ts:ArrayOfOption"/>
</message>

source: A ts:IOSpec element defining the transformation source.
sink: A ts:IOSpec element defining the transformation sink.
outputFormat: Output format name.
optionSet: Option set name.
options: A temporary option set whose options will overwrite the corresponding options of the persistent option set specified above (optionSet).

3.2 TransformationResponse

Each TransformRequest message is met with a TransformResponse message detailing the success or failure of the transformation.

Prototype

<message name="TransformResponse">
   <part name="result" type="xsd:unsignedInt"/>
   <part name="resultMsg" type="ts:stringData"/>
   <part name="resultDocs" type="ts:ArrayOfIOSpec"/>
</message>

result: Numeric error code. 0 means the transformation was successful.
resultMsg: Text error message. This may be empty, depending on the error code.
resultDocs: An array of ts:IOspec, one for each output document created. This may be empty if an error occurred.

3.3 Transformation Server's HTTP GET/POST Interface

The full functionality of Outside In Transformation Server is available through the SOAP/XML Web Services interface. In addition to this interface, the server also provides a direct interface via URL-encoded HTTP GET or POST requests.

The HTTP GET and POST interfaces provide a fast means to integrate Outside In Transformation Server into an existing application or web page. They have the added benefit of providing access to transformations without writing a line of code. All that's required is creating a properly encoded HTML link or a simple HTML form.

3.3.1 Differences Between the HTTP POST/GET and Full SOAP/XML Interfaces

The GET and POST interfaces have the following limitations:

Transformation options specific to the output format may only be specified via a named server-side option set. (No specific individual options may be set.)
The transformation parameters must be provided in UTF-8 strings (prior to being URL-encoded).

3.3.2 Using the GET/POST Interface

The HTTP interface accepts the following parameters. These parameters must be specified in URL-encoded format. For the HTTP GET interface, they are provided as query parameters appended to the Transformation Server URL. For the HTTP POST interface, they are contained in the body of the POST request.

In either case, the response to the HTTP request is identical to the one returned from the SOAP interface. It is an HTTP response the body of which contains a SOAP response encoded in XML : a TransformResponse inside a SOAP Envelope and Body.

URL encoding means that all characters that are reserved or forbidden in a URL must be represented by an escape sequence consisting of a percent sign and the hex representation of their value (for example, the ":" character is "%3A", "\" is "%5C", the space character is "", etc.).

source: This is the input file for the transformation. This string is required to be UTF-8 encoded UNICODE, prior to being URL-encoded for transmission. (Required)
sink: This is the output file for the transformation. This string is required to be UTF-8 encoded UNICODE, prior to being URL-encoded for transmission. (Required)
sourcetype: This describes the type of IO specification used for the source file. If not present, Transformation Server will inspect the source parameter and attempt to guess the specification type.
sinktype: This describes the type of IO specification used for the sink file. If not present, Transformation Server will inspect the sink parameter and attempt to guess the specification type.
format: Specifies the output format for the transformation. If this parameter is not present, HTML is assumed to be the desired output format. The valid output formats are contained in the configuration file called agent_engine_list.xml.
optionset: Specifies the option set in agent_option_sets.xml to be used in the transformation. If the set specfied is not present in agent_option_sets.xml or this parameter is not set, no option set will be used.

Transformation Server's ability to guess the type of an IO specification is very limited. Transformation Server will assume that the specification is for a file system path unless the specification begins with "http://", in which case it will assume the specification is a URL.

3.3.3 Example

The following are examples to demonstrate the interface.

3.3.3.1 Using the GET Interface

To request a transformation with an HTTP GET request, the transformation parameters and their values must be appended as query parameters to the URL address used for Transformation Server transformation requests.

For example, if Transformation Server is running on port 9000 of the local host, the input document is c:\files\sample.doc and the output document is c:\output\sample.htm, the appropriate URL for the transformation is:

http://localhost:9000/transform?source=c%3A%5Cfiles%5Csample.
   doc&sink=c%3A%5Coutput%5Csample.htm

3.3.3.2 Using the POST Interface

The POST interface uses the same parameters and URL encoding as the GET interface, but sends the parameters as the body of an HTTP POST instead of appending them to the URL.

An HTML form may be the easiest way to generate a POST request for a transformation. The following HTML could be used:

<FORM name="SOAPREQ" ACTION="http://localhost:9000/transform"
   METHOD="post" enctype="application/x-www-form-urlencoded">
<p>Input file: <br/>
<INPUT TYPE="TEXT" NAME="source" size="60"><br/>
</p>
<p>Output file: <br>
<INPUT TYPE="TEXT" NAME="sink" size="60"><br/>
</p>
<p><INPUT TYPE="SUBMIT" value="Run Transformation"></p>
</FORM>

3.3.3.3 The HTTP Response

Transformation Server's response to an HTTP request for a transformation is a SOAP XML document describing the results of the transformation request. This response is identical to that returned by the SOAP HTTP interface. This response may be parsed and consumed directly by your application, or an XSL stylesheet may be used to present this information to an end user.

3.3.4 Sample Pages

Use of the HTTP POST and GET interfaces to Transformation Server are demonstrated by the sample HTML pages TSGET.HTM and TSPOST.HTM. While the POST and GET interfaces may be used from any application that can send HTTP requests (not just a browser), inspecting the HTML source of these pages should give you a good idea of how the GET and POST interfaces may be used.

3.3.4.1 tsget.htm

TSGET.HTM is a web page that uses JavaScript to generate a URL that will request a transformation from Transformation Server. The XML response to that transformation request will be displayed in a new browser window.

If your browser is Microsoft Internet Explorer 6, you have the option of using the accompanying XSL stylesheet TSRESP.XSL to format the XML response as a Web page. Otherwise, the results will be displayed in whatever way your browser chooses to display XML documents.

3.3.4.2 tspost.htm

TSPOST.HTM is a page that contains a very simple HTML form. This form generates an HTTP POST that will initiate a transformation and return the XML response to the browser. The response will be displayed in whatever manner your browser displays XML files.

TSPOST.HTM must be edited prior to using it. The HTML form contains a URL that must be modified to reflect the TCP address where your installation of Transformation Server can be found.