Online documentation - Websydian v6.0

Users Guide | Patterns Reference | WebsydianExpress | Search
 

TransacXML Web Services Upgrade Guide

Instructions

This section includes the steps that are necessary in order to upgrade a TransacXML Web Service application from a previous version of Websydian to Websydian 5.5. It is recommended to read the Upgrade Overview before continuing with this section.

The following sections assume that the implemented web service pattern is named MyWebService.

General

Restructuring

The SoapProcessor, SoapGenerator, and ExtractSOAPBody functions have been restructured in Websydian 5.5. In this process some code and edit points have been removed from these functions. If code has been inserted in any of the deleted edit points it should be examined whether this code is still necessary and, if yes, then which edit point the code should be moved to. Please contact Websydian Support for help on this issue.

SOAP Body Element

In previous versions of TransacXML Web Services the SOAP message was handled incorrectly:

In Websydian 5.5 this has been fixed so XML documents are sent and received correctly. This also means that all previous local modifications regarding this issue now can be removed.

Remove action diagram inserted due to the above bug from the following functions:

New Objects

The following objects are new and should be compiled and built as well as all their scoped objects:

Inheritance

The previous distinction between a SOAP pattern with and without SOAP headers has turned out to be unnecessary, so these patterns have been merged. Please change the inheritance path as advised by the following instructions:

  1. The following table show how the inheritance triple should be changed:

    Inherits from Change to
    _Abstract.Soap No change
    _Abstract.SoapWithHeaders _Abstract.Soap
    HttpSoap No change
    HttpSoapWithHeaders HttpSoap

  2. Delete the entity MyWebService.Data.Envelope.Header.SOAPAction as this header is no longer used by the SOAP pattern.

  3. Delete the following fields that are no longer used by the SOAP patterns:

SoapProcessor

In most web service implementations the SoapProcessor does not need any changes to the action diagram. This means that most likely all of the previous changes that has been inserted in the SoapProcessor action diagram because of bugs can be removed. If in doubt please contact Websydian Support for advice.

In most cases the SoapProcessor does not need any modifications at all to the action diagram, so any previous modifications can safely be deleted.

Server Validation

If code has been inserted in the edit point "Subscriber validation functionality" in any of the XmlHandler functions comprised by the SoapProcessor, then the following triple should be inserted:

MyWebService.Services.SoapProcessor option NME WSYSOAP/ServerValidate
...value SYS No

Handling temporary XML documents

If it is necessary for the SoapProcessor to modify any of the XML documents then please consult the table below for information about variables that contain the object reference to the corresponding XML document.

The object references to the XML documents are stored in the variables shown in the table below.

XML document Variable
The SOAP message sent to the SoapProcessor (SOAP request). InputDocument
The payload from the SOAP request. The object references to this XML document is transferred to the XmlHandler function. InputBody
The payload for the SOAP response. This XML document is created by the SoapProcessor and the object references to the document is transferred to the XmlHandler function. It is then up to the XmlHandler function to insert elements into the XML document. OutputBody
The SOAP message that is returned to the sender (SOAP response). OutputDocument
XML document object references in SoapProcessor

Default save dir

The value in the message object SoapProcessor.Messages.DefaultSaveDir has been changed. The previous value was "c:\temp" and it has now been changed to the empty string. This has the effect that temporary files by default will be written to the current directory of the application. However, this value is in most cases overwritten by the settings in the INI/property file.

If this message object is used, then the value should end with a slash, e.g:

Configuration file changes

The entries in the configuration file has been renamed so the names explain more about the purpose of the entries.

That an extra slash has been added to the temporary file folder.

Windows

The INI file for the SoapProcessor will contain the following entries:

[WinCFnc]
MAX_CONTENT_LENGTH=10240
sourcedir=C:\Websydian Demos\webservices\temp\distra

The above section should be changed accordingly to the example below.

[TransacXML]
MAX_CONTENT_LENGTH=10240
TEMPORARY_FILES=C:\Websydian Demos\webservices\temp\distra\

Java

The property file for the SoapProcessor contains the following entries:

WinCFnc.MAX_CONTENT_LENGTH=10240

WinCFnc.sourcedir=C:/Websydian Demos/webservices/temp/distra

The above entries should be changed accordingly to the example below.

TransacXML.MAX_CONTENT_LENGTH=10240

TransacXML.TEMPORARY_FILES=C:/Websydian Demos/webservices/temp/distra/

SOAP header entries

The handling of the optional SOAP headers have been changed in Websydian 5.5. If the SoapProcessor must process any optional SOAP headers in the SOAP messages, then please consult the documentation for the SoapProcessor for information on how to do this.

XmlHandler

The SoapProcessor has been changed in the way it transfers XML documents to the XmlHandler. In previous versions of Websydian this was done using files, where the filename of the XML documents where transferred as parameters between function calls.

This has now been changed so the XML documents are kept in memory and the object references to the XML documents are instead transferred between function calls. Please look in the table below to get an overview of what has changed for the XmlHandler.

Variable Old field New fields Comment
Input BodyFile BodyInObjectStoreReference
BodyInDocument		 Object references to the XML document for the payload of the SOAP request.
Response ResponseFile BodyOutObjectStoreReference
BodyOutDocument		 Object references to the XML document for the SOAP response payload.
XML document object references in XmlHandler

Depending on how the XmlHandler is coded there are several ways to upgrade the XmlHandler to Websydian 5.5. Please consult the section below that matches your scenario.

XmlHandler contains code to create the SOAP response payload document

If it is the XmlHandler that creates the SOAP payload document then apply the following steps to the XmlHandler function:

  1. Remove the code that loaded the SOAP request payload from the file found in Input<BodyFile>. That is, the call to DomServices.CreateDocument and DomServices.LoadDocumentFromFile should be deleted.
    Instead use the fields Input<BodyInObjectStoreReference> and Input<BodyInDocument> to access the SOAP request payload.

  2. Remove the code that creates a new SOAP response payload document (delete call to WSYDOM/DomServices.CreateDocument). All operations on the SOAP response payload should instead use the fields Response<BodyOutObjectStoreReference> and Response<BodyOutDocument>.
    Also remove the call to DomServices.SaveDocumentToFile that saves the SOAP response payload.

  3. Add the following triple to the XmlHandler function:

    MyXmlHandler implement SYS Yes

XmlHandler calls function that creates the SOAP response payload document

If the XmlHandler only acts as a wrapper function delegating the responsibility for creating the SOAP response payload to another function (e.g. MyCreateXmlResponse), and the file name parameters are transferred to this function, then please apply one of following solutions.

Solution 1

The recommended solution is to modify the MyCreateXmlResponse function so it does not use files to transfer the request/response XML documents, but instead uses the document references shown in the table above. Then all object references must be transferred to the MyCreateXmlResponse function. This has the advantage that the MyCreateXmlResponse function will be simpler and the overhead of reading/writing files will be avoided.

The MyCreateXmlResponse should be modified using the following steps:

  1. Add the four object references found in the table above to the input parameters of MyCreateXmlResponse:

    MyCreateXmlResponse input FLD BodyInObjectStoreReference
    ...for VAR InputDocument
    input FLD BodyInDocument
    ...for VAR InputDocument
    input FLD BodyOutObjectStoreReference
    ...for VAR OuputDocument
    input FLD BodyOutDocument
    ...for VAR OuputDocument

    Also remember to delete the file input/output parameters as they are no longer used.

  2. In MyCreateXmlResponse delete the code that creates an XML document and loads the SOAP request payload from the input file into this document. That is, the call to DomServices.CreateDocument and DomServices.LoadDocumentFromFile should be deleted.
    Instead use the object references InputDocument<BodyInObjectStoreReference> and InputDocument<BodyInDocument> to access the SOAP request payload.

  3. In MyCreateXmlResponse delete the call to DomServices.CreateDocument that creates an XML document for the SOAP response payload. Instead use the object references OutputDocument<BodyOutObjectStoreReference> and OutputDocument<BodyOutDocument>.
    Also remember to delete the call to DomServices.SaveDocumentToFile that saves the SOAP response payload to a file.

The XmlHandler function should be modified as well:

  1. In the call to the MyCreateXmlResponse function map with object references found in the Input and Response variables.

  2. Add the following triple to the XmlHandler function:

    MyXmlHandler implement SYS Yes
Solution 2

Alternatively if you want to keep the temporary files for debugging purposes, then please apply the following steps to the XmlHandler function:

  1. Before the call to MyCreateXmlResponse make a call to DomServices.SaveDocumentToFile. Map with the following parameters:

    Input parameter Map with
    ObjectStoreReference Input<BodyInObjectStoreReference>
    ObjectReference Input<BodyInDocument>
    FileName Map with the input filename to MyCreateXmlResponse
    Encoding <Encoding.utf-8>
    version <version.default>

  2. When calling MyCreateXmlResponse use the FileName parameter as the input file to the function.

  3. After the call to MyCreateXmlResponse make a call to DomServices.LoadDocumentFromFile. Map with the following parameters:

    Input parameter Map with
    ObjectStoreReference Response<BodyOutObjectStoreReference>
    ObjectReference Response<BodyOutDocument>
    FileName Map with output filename from MyCreateXmlResponse.

  4. Add the following triple to the XmlHandler function:

    MyXmlHandler implement SYS Yes

SoapGenerator

In most web service implementations the SoapGenerator does not need any changes to the action diagram. This means that most likely all of the previous changes that has been inserted in the SoapGenerator action diagram because of bugs can be removed. If in doubt please contact Websydian Support for advice.

The SoapGenerator most likely does not need any modifications to the action diagram, so any previous modifications can safely be deleted.

Interface

The interface for the SoapGenerator function has been changed. The major change is that in previous versions of Websydian the SoapGenerator used files to store the XML documents for for the SOAP request/response. This has now been changed so the SoapGenerator as input expects the object references to the SOAP request payload.

Please see the table below for an overview.

Websydian 4.01 Websydian 5.5
Variable Field Variable Field
Input BodyFile InputDocument ObjectStoreReference
ObjectDocument
ReturnValues SOAPInFile Obsolete
BodyFile OutputDocument ObjectStoreReference
ObjectDocument
ErrorMessage Output ErrorDescription
ReturnStatus Environment *Returned status
Response Encoding Obsolete
SoapGenerator input parameters changes in Websydian 5.5

Make the following changes to the function that calls the SoapGenerator (SGCaller):

Insert the following triples:

SGCaller local FLD ObjectStoreReference
...for VAR InputDocument
local FLD ObjectDocument
...for VAR InputDocument
local FLD ObjectStoreReference
...for VAR OuputDocument
local FLD ObjectDocument
...for VAR OuputDocument

Before the call to the SoapGenerator function insert the following code (please note that no error checking has been inserted):

Call DomServices.CreateDocument

Set InputDocument = DomServices.CreateDocument/Output

Call DomServices.CreateDocument

Set OutputDocument = DomServices.CreateDocument/Output

Call DomServices.LoadDocumentFromFile

  // Map InputDocument<ObjectStoreReference>

  // Map InputDocument<ObjectDocument>

  // Map with the input file (previously mapped to Input<BodyFile> in the call to SoapGenerator)

After the call to the SoapGenerator function insert the following code (please note that no error checking has been inserted):

Call DomServices.SaveDocumentToFile

  // Map OutputDocument<ObjectStoreReference>

  // Map OutputDocument<ObjectDocument>

  // Map with the output file (previously returned from the SoapGenerator in ReturnValues<BodyFile>)

  // Map with the desired encoding (e.g. UTF-8)

  // Map with the desired XML version (e.g. 1.0)

Call DomServices.DestroyDocument

  // Map with InputDocument variable

Call DomServices.DestroyDocument

  // Map with OutputDocument variable

Error handling

If the SoapGenerator encounters an error preventing it from fulfilling the request then it aborts with *Returned status set to *Error.

For more detailed error information please use the fields found in the Output variable (see table below).

Field in Output variable Usage
ErrorDescription Contains a textual description of the error.
ContentType If a response was succesfully returned then this field contains the content type of the response.

It is considered to be an error if this field is different from "text/xml".
HttpStatus If a response was returned from the publisher then this field contains the HTTP status for the response.

Any value different from 200 (OK) is considered to be an error.
Output fields for the SoapGenerator function

Furthermore, if a DOM error ocurred then more detailed error messages can be fetched by using the ErrorPop function.

Configuration file changes

The entries in the configuration file has been renamed so the names explain more about the purpose of the entries.

That an extra slash has been added to the temporary file folder.

Windows

The INI file for the SoapGenerator contains the following entries:

[WinCFnc]
MAX_CONTENT_LENGTH=10240
sourcedir=C:\Websydian Demos\webservices\temp\distra

The above section should be changed accordingly to the example below.

[TransacXML]
MAX_CONTENT_LENGTH=10240
TEMPORARY_FILES=C:\Websydian Demos\webservices\temp\distra\

Java

The property file for the SoapGenerator contains the following entries:

WinCFnc.MAX_CONTENT_LENGTH=10240

WinCFnc.sourcedir=C:/Websydian Demos/webservices/temp/distra

The above entries should be changed accordingly to the example below.

TransacXML.MAX_CONTENT_LENGTH=10240

TransacXML.TEMPORARY_FILES=C:/Websydian Demos/webservices/temp/distra/

SOAP header entries

The handling of the optional SOAP headers have been changed in Websydian 5.5. If the SoapGenerator must process any optional SOAP headers in the SOAP messages, then please consult the documentation for the SoapGenerator for information on how to do this.