Defining a XSD response message for TCP/WMQ

The Transport Map panel allows you to define how you want to process an XML response message from a TCP or WMQ transport configured to process replies. This panel allows you to:

  • Specify an XSD that will be used to parse the XML response message
  • Specify how to map parsed response data to the output map variables
  • Specify the maximum capacity of array variables that are populated with data from the XML response message.

Assumptions

The following is assumed:

  • You have configured a TCP or WMQ transport with options that allow for a response message to be received and processed.

  • The business application is sending replies in XML

  • You are familiar with the XML Schema Definition language.

  • If the XML Schema has import statements, then all other required XSDs are on file systems that are accessible by the Workbench as you define the transport map.

XSD limitations

You can review a list of XSD limitations before you define your TCP transport map.

Downloading the sample XSD file

Download this sample XSD file, and note the folder where it is stored.

Sample XSD file

The sample XSD file will look like this:

Specifying the XSD in the transport map

  1. In the Transport Map window, under the From Enterprise tab, select the Format down-arrow, and then select XSD.
  2. Select the XSD file by entering its location information in the XSD File parameter:
    • If the XSD is located on a web server, type a URL starting with http(s) in the XSD File parameter.
    • If you know the location and name of the file, you can type it into the XSD File parameter, specifying the full path of the file. For example: C:/path/xsdfilename.xsd.
    • You can use a File chooser dialog to locate the XSD file on your file system. To do so select the browse button.
      After you have selected the file, the file name will appear in the XSD File parameter.
  3. Select the Query button.

    Assuming the XSD is valid and contains at least one element, the Root Element pick list is populated with elements found in the XSD file.
  4. Select the Root Element:
    Use the Root Element down-arrow, and pick the appropriate element from the list.
    The XSD structure is displayed below the Root Element at the bottom of the From Enterprise section of the transport map window.
    The XSD structure appearance includes:
    • XSD elements nested within other XSD elements, such as elements belonging to complex types, appear indented below their parent element.
    • Attributes appear indented under the element they belong to and are italicized.

    • Arrays are identified by the Table keyword in the Type column.

      Array handling

      In the sample XSD, the book element has maxOccurs="unbounded" which indicates that there could be an array of books.
      Therefore, the book element is identified as a TABLE in the Transaction Server.


      You can specify the number of rows of Table data you want to process by entering a value in the Rows In column. Any additional row data received in the response message will not be processed. This dimension value is used to determine the size of output map variables

  5. Map the XML tags to logical variables
    To automatically generate logical variables with the appropriate size (in the case of arrays) and data type, select the Map Parms button.

    The map variables are automatically added to the transport map Output tab and the XSD element structure.
    It is recommended that the Map Parms button be used to ensure the best mappings between the XML Schema variable types and map variable data types.
    Also notice that all elements defining a book have their Count set to the numbers specified in the Rows In parameter, in this example 5.

    If mapping an XML schema tag of type time, manually adjust the variable associated with the XML element to STRING instead of TIMESTAMP, otherwise the mapping will cause an error when the XML response message is processed.

    Alternatively, logical variables can be created manually and then mapped to XML tags.

  6. When you have completed making your modifications select Save.

Using the transport map in a trigger

When you reference the transport map using a Transaction action in a trigger you can see the output variables and map them to device variables or trigger variables. If the XML in the response message has multiple rows, you can use the output variable (that ends in _nbrRows) as shown in the example below, to determine how many rows are being returned. With reference to the example on this page , the XML can be sent without any book elements. In this situation an attempt to use the 'book_price[ ]' output variable in a Set action would result in an -5209 ( Action variable is not serviced) error. The value of books_book_nbrRows will be set to 0. You can use the If action to test the value of the books_book_nbrRows variable before proceeding with accessing output variables associated with the book element.

Related topics

XSD limitations