Online documentation - Websydian v6.5 |
Upgrade 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.
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.
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:
The following objects are new and should be compiled and built as well as all their scoped objects:
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 |
Delete the entity MyWebService.Data.Envelope.Header.SOAPAction as this header is no longer used by the SOAP pattern.
Delete the following fields that are no longer used by the SOAP patterns:
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.
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 |
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 |
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:
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.
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\
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/
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.
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. |
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.
If it is the XmlHandler that creates the SOAP payload document then apply the following steps to the XmlHandler function:
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.
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.
Add the following triple to the XmlHandler function:
MyXmlHandler | implement SYS | Yes |
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.
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:
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.
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.
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.
In the call to the MyCreateXmlResponse function map with object references found in the Input and Response variables.
Add the following triple to the XmlHandler function:
MyXmlHandler | implement SYS | Yes |
Alternatively if you want to keep the temporary files for debugging purposes, then please apply the following steps to the XmlHandler function:
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> |
When calling MyCreateXmlResponse use the FileName parameter as the input file to the function.
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. |
Add the following triple to the XmlHandler function:
MyXmlHandler | implement SYS | Yes |
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.
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 |
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
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. |
Furthermore, if a DOM error ocurred then more detailed error messages can be fetched by using the ErrorPop function.
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.
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\
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/
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.