Creating a transport map with an XSD payload

This page describes the support for using XML Schema Definition (XSD) files to create transport maps.

The XSD transport map is used when XML payload needs to be generated from an XSD file.
The transport map allows to specify the location of the XML definition file and render it so that XML tags can be mapped to variables.

The XSD payload is only available for the following transports:

  • JMS
  • MSMQ
  • TCP
  • WMQ

Assumptions

The following is assumed:

  • You are familiar with the XML Schema Definition language.
  • You know how to create a transport that supports the XSD payload.
  • If the XML Schema has import statements, then all other required XSDs are located in the correct location(s).

Limitations

The current implementation of the XSD support is limited to tags, arrays, and attributes.

The Transaction Server does not use an XML validating parser and will not validate the XML received against the XML Schema. Therefore, the XML must reflect the XSD structures to ensure the correct match of XML tag values to variables.

The only facet implemented is maxLength which is used to determine the size of the string in a logical variable.

XSD constructs not supported by the Transaction Server

Currently, the Transaction Server does not process and ignores the following XML Schema constructs:

  • Choice
    • Unless all the elements in the choice selection are strings, the XML Schema choice construct will result in an error when processing the XML.
  • Namespace
    • The Transaction Server XSD Schema handling is not namespace aware.

The following shows  an example of the XSD constructs that are not supported by the Transaction Server:

XSD element XSD example
choice <xsd:group name="priceGroup">
<xsd:choice id="pg.choice">
<xsd:element name="fullPrice" type="fullPriceType"/>
<xsd:element name="salePrice" type="salePriceType"/>
<xsd:element name="clearancePrice" type="clearancePriceType"/>
<xsd:element name="freePrice" type="freePriceType"/>
</xsd:choice>
</xsd:group>
Attributes The Transaction Server supports attributes but not the following options on attributes:
use="prohibited" is ignored.
form="qualified" is ignored and is sent with the XML Schema default of form="unqualified".

Unsupported XML schema types

The following XML schema types are not supported by the Transaction Server:

  • base64Binary
  • hexBinary
  • duration
  • NOTATION

If the XSD contains elements of the above types, they must be optional or set with nillable="true" to be handled by the Transaction Server; otherwise, it is will not be possible for the Transaction Server to generate a valid XML from the transport map XSD or successfully processed an incoming XML in the listener.

Data types are mapped as follows to XML Schema types:

XML schema type
 Data Type
boolean BOOL
byte INT1
date TIMESTAMP
dateTime TIMESTAMP
decimal FLOAT8
double FLOAT8
float FLOAT4
gDay UINT1
gMonth UINT1
gMonthDay STRING
gYear UINT4
gYearMonth STRING
int INT4
integer INT8
long INT8
short INT2
string STRING
token STRING
normalizedString STRING
language STRING
Time TIMESTAMP
unsignedByte UINT1
unsignedInt UINT4
unsignedLong UINT8
unsignedShort UINT2
positiveInteger UINT8
negativeInteger INT8
nonPositiveInteger INT8
nonNegativeInteger UINT8
anyURI STRING
QName STRING
NCName
 STRING
Name
 STRING

Rendering the XSD in the transport map

To use the XSD payload transport map you must first select a JMS, MSMQ, TCP, or WMQ transport, then select XSD from the Format drop down list.

The To Enterprise section of the transport map changes to accommodate an XSD format.

Step 1: Specifying the location of the XSD file

Consider the following when specifying a value for the XSD File box:

  • If the XSD is located on an HTTP server, type a URL starting with http in the XSD File box.
  • If you know the location and name of the file, you can type it into the XSD File box, specifying the full path of the file; for example, C:/path/xsdfilename.xsd.
  • If you do not know the exaction location of the file, click the browse button.

Step 2: Finding the XSD elements using the Query button

Once the XSD file name is specified (through a URL or a file name), click the Query button.


Assuming the XSD file contains elements that can be rendered by the Transaction Server, the Root Element drop-down list is populated with the elements found in the XSD file.

Step 3: Rendering the XSD element structure

Selecting one of the elements from the Root Element drop down list will display its structure (assuming it is correctly defined and only use XSD features recognized by the Transaction Server).

XSD elements nested in other XSD elements, such as elements belonging to complex types, appear indented below their parent element.

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

Attributes appear indented under the element they belong to and are italicized.

Step 4: (Optional) Automatically generate logical variables using the Map Parm button

To automatically generate logical variables with the correct count (in the case of arrays) and data type, use the Map Parm button.

It is recommended to use the Map Parms button to ensure the best mappings between the XML Schema variable types and data types.

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

Step 5: (Optional) Click the Validate button to display a sample XML

You can click the Validate button to view a sample XML of what the Transaction Server will send to Enterprise application.

Values are substituted by the logical variable names between [ ].

When a fixed attribute is defined for an XSD element, then the defined value for that fixed attribute is used instead of the logical variable name between [ ].

At run time, if the tag is mapped to a logical variable and the value is not equal to that specified in the fixed attribute, an error occurs and the XML is not generated.

Parameter descriptions

Option Description
XSD File Required. The location of the XSD file.
It can be a URL in the form of http://host.com/path/file.xsd or
a file with the absolute path in the form of C:/Directory/file.xsd.
To locate a file on the local computer or network use the button .
Root Element Required. Populated when the Query button is clicked.
Assuming the XSD is valid and contains at least one element, the Root Element drop-down list shows all the elements defined in the XSD.
Parameter Required. Automatically populated after selecting a root element.
XSD elements can be identified as Structures or Tables where they are complex.
When an element is identified as Table by the Transaction Server it is in fact an array, where you can specify the maximum size of the array (see Value Parameter description below)
Elements belonging to a structure or table are indented below their parent tag.
Type
Required. The Type column shows the parameter type. Unless the XSD element is complex, the type is the XSD type.
Parm Type
Required. Refers to incoming or outgoing elements. For this transport map, the Parm Type is always In.
Variable
Optional. This is the name of the variable associated with the XML tag.
This name is automatically generated when using the Map Parms button or manually added from the list of logical variables.
Value  /
Rows In
 Optional. Only editable when the parameter type is set to Table when XML Schema elements are defined with maxOccurs="unbounded".
Default value is 1 which has the same effect as if it was defined as a structure.
It must be a positive integer.
If you click the Map Parm button to generate the logical variables, the logical variables associated with table elements will automatically have their count updated with the number specified in the Row In column

Creating a transport map that uses an XSD payload to generate XML

This example is a step by step guide when using an XSD transport map to generate XML to be sent to the enterprise application.

Assumptions

The following is assumed:

  • You know how to use the Workbench.
  • You know how to create triggers, transports, and transport maps.
  • You have created a transport (such as a TCP, MSMQ, WMQ or JMS transport) that supports an XSD payload.

Example XSD file

Use the following to create a sample XSD file.

<?xml version="1.0" encoding="utf-8" ?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<xsd:element name="books" type="BooksForm"/>
<xsd:complexType name="BooksForm">
   <xsd:sequence>
    <xsd:element name="book"
        type="BookForm"
        minOccurs="0"
        maxOccurs="unbounded"/>
    </xsd:sequence>
</xsd:complexType>
<xsd:complexType name="BookForm">
   <xsd:sequence>
      <xsd:element name="author" type="xsd:string"/>
      <xsd:element name="title" type="xsd:string"/>
      <xsd:element name="genre" type="xsd:string"/>
      <xsd:element name="price" type="xsd:float" />
      <xsd:element name="pub_date" type="xsd:date" />
      <xsd:element name="review" type="xsd:string" minOccurs="0"/>
   </xsd:sequence>
  <xsd:attribute name="id" type="xsd:string" use="required"/>
  </xsd:complexType>
</xsd:schema>

Create a file using a text editor, and then copy and paste the XML into the new file. Also, note the directory where you store the file.

Step 1: Adding a transport map that uses an XSD payload

  1. From the Workbench left pane, expand the node that you want to add the transport map to.
  2. Expand Enterprise, right-click the Transport Maps icon to display its pop-up menu, and then click New.
    The Transport Map window appears.
  3. Name the transport map as appropriate, and then set the Version Mismatch option to either Pass or Fail.
  4. Use the Transport Type down arrow to select the transport type. This will limit the display of transports that appear in the Transport Name list.
  5. Use the Transport Name down arrow to select the transport that will send the XSD payload.
  6. Under the To Enterprise section, click the Format down-arrow to display a list.
    The XSD File and Root Element parameters become available.

       
  7. In the XSD File box, type the path and file name of the sample  XSD file, or use the  button.
  8. Click Query.
    The XSD is rendered in the transport map as follows:

Array handling

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

Using the $NULL macro

When a tag always needs to be present in the XML but is never assigned a value, the $NULL macro can be used to generate an empty tag. If the element is nillable (for example, nillable="true" in the XSD), then the tag generated is <tag xsi:nil="1"></tag>; otherwise, the tag is the empty tag or <tag></tag>.

Step 2: Generating the mapping from XML tags to variables

The following assumes that the application is expecting a maximum of 5 books.

  1. Under the Value column, in the Rows In parameter, type 5. 
  2. Click Map Parms.

Array variable mapping

After you click Map Parms, all the elements defining a book have their Count set to the value of Rows In, including the attribute.

The completed transport map will appear similar to the following:

3. Click Validate (optional), and then click Save.

Step 3: Creating a trigger to use the XSD payload transport map as an action

The following assumes that you know how to create a trigger and add actions using the Canvas Editor. For this example, an on-demand trigger will be created that will use the transport map you just created.

  1. From the Workbench left pane, expand the node that contains your project.
  2. Click the Projects icon, and then open the appropriate project
  3. From the bottom of the project tab, click the New button.
    The New Trigger window appears.
  4. Name the trigger.
  5. From the Event tab, click the Trigger Event Type down-arrow, and then select On-Demand.
    It is  assumed the New Trigger window defaulted to the Canvas Editor.
    The next step is to add the transport map that you just created as an action.
  6. From the left pane of the New Trigger window, locate and then expand the action group named Enterprise Communications, and then drag the Transaction action on the canvas.
  7. Double-click the Transaction action to display its parameters.
  8. Use the Transport map down-arrow, and then select the example MyXSDTransportMap.
  9. Make sure the Input tab has the focus.

The book_nbrRows parameter (which is optional) indicates how many rows the actual payload contains. In this example, though the array can accommodate up to 5 book elements. For this example, 2 will be processed.

Viewing variables used in trigger

Assuming the variables used in the trigger contain the following information:

Upon execution of the trigger, the XML will be as follows:

<?xml version="1.0" encoding="UTF-8"?>
   <books xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
      <book id="F-132" >
         <author>author</author>
         <title>Future</title>
         <genre>fiction</genre>
         <price>23.99</price>
         <pub_date>2009-07-02</pub_date>
   </book>
   <book id="N-335" >
       <author>writer</author>
       <title>Romance</title>
       <genre>novel</genre>
       <price>11.78</price>
       <pub_date>2003-05-05</pub_date>
   </book>
  </books>

Unmapped variable

In this example, the tag review is not mapped to a trigger variable and is not required (minOccurs="0" in the XSD); thus, the tag is not sent. 

Related topics

Defining an ASCII message payload

Creating a payload of freeform text

Defining the XML payload

Adding a custom payload

Adding a map message as the payload

Using WebSphere MQ extended attributes