Listener XSD format

To allow the Transaction Server to receive and process XML described by XML Schema Definition Language (XSD), a listener must be created with the XSD payload type.

Once the payload type is selected for a listener, the listener will only process messages of that type. Any other message type cause the listener to reject the message and log an error.

The XSD payload is supported by all listeners:

  • TCP
  • MSMQ
  • JMS
  • WMQ

Assumptions

  • You know how to create a listener.
  • You have an understanding of XSD and knowledge of the application program that will be sending the XML messages to the node. In addition, you are able to identify an XML tag that will be used to contain the listener map name.

Specifying the listener map ID

For all the listeners, the listener map identifier can be specified as:

  • a default listener map
  • an xpath expression
  • a JMS message header property (JMS listeners only)

The listener map is selected in the following order:

1) JMS message header property (JMS listener only)

      If the listener map identifier is specified as a JMS message header property:

  • The JMS message contains the JMS header property specified in the listener and the value points to a valid listener map, the listener map identifier is used to retrieve the listener map to process the XML.
  • The JMS message contains the JMS header property specified in the listener and the value does not point to a valid listener map, the listener logs an error and no data is processed.
  • The JMS message does not contain the JMS header property specified in the listener and there is a default listener map, the default listener map identifier is used to retrieve the listener map to process the XML.
  • The JMS message does not contain the JMS header property specified in the listener and there is no default listener map, the listener logs an error and no data is processed.

2) XPath expression (all listeners, including JMS)

  • The XML contains the tag specified in the listener xpath expression and the tag value points to a valid listener map ID. The listener map ID is used to retrieve the listener map to process the XML.
  • The XML contains the tag specified in the listener xpath expression and the tag value does not point to a valid listener map ID, and there is a default listener map ID specified. The default listener map ID is used to retrieve the listener map to process the XML.
  • The XML contains the tag specified in the listener xpath expression and the tag value does not point to a valid listener map id, and there is no default listener map id specified.The listener logs an error and no data is processed.

3) Default Listener Map Id

The default listener map ID is used when:

  • There is no other listener map ID specified (no JMS message header properties nor xpath expression).
  • There is a JMS message header property specified but the property does not exist in the JMS message being processed.
  • The xpath expression does not resolve to a valid listener map ID.

Using the default listener map

When providing only a default listener map on the listener XSD Payload tab, all messages received by the listener will be processed by the listener map name specified in the Default Listener Map parameter.

Restriction

Using the default listener map implies that all XML messages received by the listener must comply with the XSD used to create the listener map.
There can only be one listener map per listener when using the default listener map.

Using the xpath expression

For more flexibility and allowing the listener to process multiple XML formats, you can use the xpath expression. The xpath expression is used to locate the listener map ID in the XML.

The xpath expression must be the absolute path to the XML element containing the listener map ID value. It must start with the forward slash ( / ) character followed by the root element as in /root/tag1/tag2 for instance. The xpath expression cannot refer to an attribute.

The following examples show the XSD and corresponding XML:

Example XSD:
<?xml version="1.0"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="EmployeeRecord">
  <xs:complexType>
     <xs:sequence>
       <xs:element name="employee" type="fullpersoninfo"/>
       <xs:element name="employeeId" type="xs:string" />
     </xs:sequence>
   </xs:complexType>
</xs:element>
<xs:complexType name="personinfo">
  <xs:sequence>
    <xs:element name="firstname" type="xs:string"/>
    <xs:element name="lastname" type="xs:string"/>
  </xs:sequence>
</xs:complexType>
<xs:complexType name="fullpersoninfo">
  <xs:complexContent>
    <xs:extension base="personinfo">
      <xs:sequence>
        <xs:element name="address" type="xs:string"/>
        <xs:element name="city" type="xs:string"/>
        <xs:element name="country" type="xs:string"/>
      </xs:sequence>
    </xs:extension>
  </xs:complexContent>
</xs:complexType>
</xs:schema>
Example XML:
|<?xml version="1.0" encoding="UTF-8"?>
<EmployeeRecord>
  <employee>
   <firstname>James</firstname>
   <lastname>Bond</lastname>
   <address>MGM Studio</address>
   <city>Hollywood</city>
   <country>USA</country>
  </employee>
<employeeId>ID-007</employeeId>
</EmployeeRecord>

Using msgId as the listener map id, the xpath expression to specify is:
    /EmployeeRecord/msgId.

There must be a listener map named ID-007 created for the current node.

Using the JMS message header property

JMS listeners can have message header properties, and you can use this property to define the listener map ID. In this case,  you must select the Specify Mapand Sequence Keys in Header check box, and then type the name of the JMS message header property in the Map Key box.

The listener map ID  is the value associated with the JMS message header property.
The JMS text message body is expected to contain an XML.

Example:

A JMS Message is received with the following properties

  • customMsgId: ID-0009
  • operationCode: CRK01
  • destination: internal

and the listener Map Key parameter contains: customMsgId, there must be a listener map with the name of ID-0009 which contains the mapping based on the XSD matching the XML received as the JMS message body.

Parameter descriptions

To add an XSD format to a listener, follow these steps:

  1. From the Listener window, click the Payload tab.
  2. Use the Format down-arrow, and then select XSD.

    The Payload section changes to accommodate the XSD option.

The XSD Payload tab has the following parameters.

Map xPath

An XML absolute xPath expression, starting at the root element and pointing to an element tag whose value will be used to identify the listener map id.

Sequence xPath

Currently not used.

Default Listener Map

The name of the listener map id to use when a message is received by the listener.

Termination

1(TCP Listeners only)

Required. A character or string or control characters that indicate the end of the message (may or may not coincide with the end XML tag).

Specify Map and Sequence Keys in Header

2(JMS Listeners only)

Indicates if the listener map name should be located in the JMS message header properties.

Map Key

3(JMS Listeners only)

Required when Specify Map and Sequence Keys in Header check box is selected.
The JMS message header property whose value will be used to identify the listener map id.

Sequence Key

4(JMS Listeners only)

Currently not used.

Related topics

Creating a TCP listener

Creating a MSMQ listener

Creating a JMS listener

Creating a WMQ listener

Creating a listener map with an XSD payload