Message mappers

A message mapper is a mechanism that takes an XML message and converts it to a CommandProperty object. It provides a common interface so that messages can be converted to CommandProperty objects and used by all WebSphere Commerce components.

The CommandProperty object is a representative of a controller command. The object contains the command name to be executed, the command properties when executing the command, and the parameters of the command. The purpose of the message mappers is to convert inbound request messages into controller commands to be executed by an adapter. Although they can be used by all components of WebSphere Commerce to map data into a extended TypedProperty object, the main purpose for message mappers is converting XML objects into common Java objects that represents controller commands.

The CommandProperty datatype is composed of the following three parts:

commandName

The name of the command to be executed, in the form of a string.

requestProperties

The command properties when executing the command, in the form of a TypedProperty object.

executionProperties

The control data for executing the command in the form of a TypedProperty object.

Supported adapters, such as the Program Adapter, and WebSphere Commerce components can both call a message mapper. For both, the message mapper performs the following tasks:

• Receives an XML message.

• Converts the message to a CommandProperty object.

• Returns null if the XML message cannot be converted.

Inbound messages are sent to WebSphere Commerce by back-end systems or external systems to request some sort of action. In order for WebSphere Commerce to perform that action, the XML message must be processed by the message mapper to determine what action has been requested. WebSphere Commerce includes two message mappers at installation: the XML message mapper for parsing XML integration messages, and the legacy message mapper for parsing back-end integration legacy messages.

The CommandProperty object represents a WebSphere Commerce command to accommodate the requirements from the supported device adapters. Other components can also use the message mapper mechanism to convert messages to CommandProperty objects.

The lifecycle of a message mapper exists throughout the WebSphere Commerce instance. It is initialized when an instance is started and it resides as long as the instance runs. WebsSphere Commerce provides three message mappers: XML message mapper, XML message mapper for SOAP message, and the legacy message mapper.

The WebSphere Commerce configuration file lists all possible message mappers, and includes their name, class, device format, whether they are available, and specific configuration parameters. To locate the parameters for a certain message mapper, find the component name in the MessageMapperGroup. Since each message mapper may have different configuration attributes, each has a separate MessageMapperGroup element. The only requirement for the format of the configuration parameters element is that the attributes must be name-value-pairs. This allows the message mapper configuration parameters to be easily converted to a TypeProperty object.

The following lists the parameters for each individual message mapper:

name

The name of the message mapper. This name will be used by the command which is expecting to parse a message with only this message mapper. To use the message mapper with HTTP or IBM MQ set the enable attribute of the mapper to true. We must also add the name of the mapper to the corresponding adapter section.

<HttpAdapters display="false">
<HttpAdapter deviceFormatTypeId="-10000" enabled="false" deviceFormatType="XmlHttp" deviceFormatId="-10000" name="XML/HTTP" factoryClassname="com.ibm.commerce.programadapter.HttpProgramAdapterImpl">
<ProgramAdapter>
<SessionContext class="com.ibm.commerce.messaging.programadapter.security.CredentialsSpecifiedProgramAdapterSessionContextImpl">
<SessionContextConfig /> 
</SessionContext>
<Configuration supportedMessageMappers="WCS.SOAPINTEGRATION, WCS.INTEGRATION" supportedMethods="POST, M-POST" supportedContentTypes="text/xml, text/xml; charset=UTF-8, text/xml-SOAP, text/xml; charset=utf-8" supportedCharacterEncoding="ISO8859-1, UTF-8, utf-8" /> 
</ProgramAdapter>
</HttpAdapter>
</HttpAdapters>

class

The class name containing the implementation of the message mapper interface.

messageMapperId

The ID for the message mapper. Each message mapper ID must be unique.

enable

Indicates whether the message mapper should be used and initialized or not. If this value is set to "true", the message mapper is initialized at the startup of the instance and is available. If this value is set to "false", the message mapper is disabled.

EcInboundMessageDtdFiles

The list of DTD files which are used to parse an inbound XML message.

EcInboundMessageDtdPath

The file location where the DTD files listed in EcInboundMessageDtdFiles can be found.

EcSystemTemplateFile

The system template file that ships with WebSphere Commerce. Users will typically set it "" if it is a customized message mapper.

EcTemplatePath

The location where the system template file can be found.

isValidating

The XML parser shipped with WebSphere Commerce has a feature (enabled by default) to validate an inbound XML message with its corresponding DTD or not. To disable it, enter "false".

EcTemplatePath

The location where the user-defined message template file can be found.

EcUserTemplateFile

The file name of the user- defined message template file.

EcSaxParserClass

The class name of the parser will be used. By default, it will use org.apache.xerces.parsers.SAXParser.

DebugMode

The debug option for messagemapper. By default, it is "FALSE". When the value is "TRUE", all message template definition files (for example, user_template.xml, sys_template.xml) and DTD files will be reloaded when an inbound message is received by the IBM MQ listener.

EmptyElementClearsData

The flag that specifies how empty elements of inbound XML messages should be handled. By default it is set to "FALSE". When set to "FALSE", empty elements of inbound XML messages will be discarded and not passed to the target command. When this flag is set to "TRUE", all empty elements of inbound XML messages will be treated as passing empty strings to the target command.

DuplicateCreatesArray

The flag that specifies how duplicate elements with the same XPath entries found in the input XML should be handled. By default it is set to "FALSE". When set to "FALSE", duplicate elements found in the input XML will overwrite the previous value. When set to "TRUE", then duplicate elements found in the input XML will be converted to arrays of values under the key used by the request properties.

ParserFeatureList

Specify the parser feature. For example, ParserFeatureList="http://apache.org/xml/features/nonvalidating/load-external-dtd=false". For more information see, Apache Xerces2. To specify multiple features use a comma-separated list. By default, the value of the isValidating attribute in our message mapper is true. If the isValidating attribute is false, and the value of the ParserFeatureList is http://apache.org/xml/features/nonvalidating/load-external-dtd=false,http://xml.org/sax/features/validation=true; then the ParserFeatureList value overrides the value of the isValidating attribute.

XML message mapper

The XML message mapper is responsible for converting the XML data from inbound XML messages to CommandProperty objects. It is an extension of the ECSAX parser. The XML message mapper found in the WebSphere Commerce configuration file should look similar to the following:

<MessageMapper messageMapperId="-1"
classname="com.ibm.commerce.messaging.programadapter.messagemapper.ecsax.ECSAXMessageMapper"
enable="true"
name="WCS.INTEGRATION">
<configuration/>
</MessageMapper>

When the XML message mapper parses an inbound XML message, it gets the document type, the version if it is available, and the element name, one by one from the XML documents in the message. The message mapper looks up the template document defined in the ECTemplate element of the template definition file. The template document tells the message mapper the following information:

• From which element the tag mapping should be started.

• Which tag template to use.

• The command name to be invoked by the inbound message. The command could be an existing WebSphere Commerce controller command or a new one that you have created.

Once the tag mapping has started, the message mapper looks in the TemplateTag, as defined in the ECTemplate file to determine the field name and type based on the XPath generated from the inbound XML message, then sets a value for that field. The field and value pairs are stored in a TypedProperty hash table of either commandProperty or messageProperty, based on the value in the FieldInfo attribute for that field. After the whole inbound message is parsed successfully, a PropertyCommand object is returned, which contains the command name as well as the commandProperty and messageProperty objects.

To support different versions for one message, multiple template document can be specified. For example,

<TemplateDocument>
<DocumentType version='1.0'>Update_NC_ProductInventory</DocumentType>
<StartElement>Update_NC_ProductInventory</StartElement>
<TemplateTagName>ProductInventory10Map</TemplateTagName>
<CommandMapping>
<Command CommandName='ProductInventoryUpdate' />
</CommandMapping>
</TemplateDocument>

<TemplateDocument>
<DocumentType version='2.0'>Update_WCS_ProductInventory</DocumentType>
<StartElement>Update_WCS_ProductInventory</StartElement>
<TemplateTagName>ProductInventory20Map</TemplateTagName>
<CommandMapping>
<Command CommandName='ProductInventoryUpdate' />
</CommandMapping>
</TemplateDocument>

If the configuration element is empty, then the Messaging element will be used. The Messaging is found inside WebSphere Commerce configuration file.

XML message mapper for SOAP messages

The XML message mapper for SOAP messages is responsible for extracting the XML data from inbound SOAP messages and converting it to CommandProperty objects. It is an extension of the ECSAX parser. The message mapper found in the WebSphere Commerce configuration file should look similar to the following:

<MessageMapper classname="com.ibm.commerce.messaging.programadapter.messagemapper.ecsax.ECSAXMessageMapper"
enable="false"
messageMapperId="-3"
name="WCS.SOAPINTEGRATION">
<configuration EcInboundMessageDtdFiles=""
EcInboundMessageDtdPath="messaging"
EcSystemTemplateFile="webservice_template.xml"
EcTemplatePath="messaging"
isValidating="false"
DebugMode="FALSE"
EmptyElementClearsData="FALSE" />
</MessageMapper>

Legacy message mapper

The legacy message mapper is responsible for converting the data from inbound legacy messages to CommandProperty objects. The legacy message mapper found in the WebSphere Commerce configuration file should look similar to the following:

<MessageMapper messageMapperId="-2"
    classname="com.ibm.commerce.messaging.programadapter.messagemapper.nclegacy.NetCMessageMapper"
    enable="true">
    name="NC.LEGACY">
<configuration/>
</MessageMapper>

• Inbound message template definition files
  WebSphere Commerce provides an XML message mapper which can be used to map inbound XML messages to WebSphere Commerce command interfaces based on the inbound XML message template definition files.

• TemplateDocument element of a template definition file
  For each inbound XML message, there must be at least one template document defined in the message. This is defined in the TemplateDocument element.

• TemplateTag element of a template definition file
  Template definition files use the TemplateTag element and the TemplateDocument element. Several TemplateTag elements can be defined for each inbound XML message. Each TemplateTag element must be linked to a TemplateDocument element using the name attribute.

• Adding message mappers
  To add a new message mapper, we must manually add it to the group of message mappers in the WebSphere Commerce configuration file.

• Removing message mappers
  To remove a message mapper, we must manually remove it from the group of message mappers.

Related concepts
WebSphere Commerce configuration file (wc-server.xml)

Related tasks
Adding message mappers
Removing message mappers

Related reference
TemplateTag element of a template definition file