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 HCL 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 HCL Commerce to map data into an 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 HCL 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 HCL Commerce by back-end systems or external systems to request some sort of action. In order for HCL Commerce to perform that action, the XML message must be processed by the message mapper to determine what action has been requested. HCL 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 an HCL 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 life cycle of a message mapper exists throughout the HCL Commerce instance. It is initialized when an instance is started and it resides as long as the instance runs. HCL Commerce provides three message mappers: XML message mapper, XML message mapper for SOAP message, and the legacy message mapper.

The HCL 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. You 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 that contains 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 start-up of the instance and is available. If this value is set to false, then 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 HCL Commerce. It is typically set it to "" for customized message mappers.

EcTemplatePath

The location where the system template file can be found.

isValidating

The XML parser shipped with HCL Commerce has a feature to validate an inbound XML message with its corresponding DTD or not. This feature is enabled (set to true) by default. To disable it, set this to false.

Note: For HCL Commerce 9.1.12.0, the WCS.INTEGRATION mapper isValidating parameter is set to true by default. The ParserFeatureList is also updated. This configuration prevents the XML parser from parsing external general entities and external parameter entities.

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 set to false. When the value is set to 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, 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.

Note: For HCL Commerce 9.1.12.0 and 9.1.13.0, the WCS.INTEGRATION mapper ParserFeatureList parameter is set to

"http://apache.org/xml/features/nonvalidating/load-external-dtd=false,http://xml.org/sax/features/external-general-entities=false,http://xml.org/sax/features/external-parameter-entities=false"

. The isValidating parameter is also updated. This configuration prevents the XML parser from parsing external general entities and external parameter entities.

XML parser enhancement

The security of XML processing in inbound web services that use the program adapter and WCS.INTEGRATION message mapper was strengthened.

The message mapper configuration in wc-server.xml is as follows:

<configuration isValidating="true" ParserFeatureList="" isSanitizationEnabled="true" WhiteListSchemes="http,https,ftp,sftp"
WhiteListDomains="xml.cxml.org" isLocalEntityEnabled="true"/>

The new feature offers a more flexible way to prevent users from accessing remote resources hosted by untrusted sites. The parser will validate and only allow requests which adhere to WhiteListSchemes and WhiteListDomains properties. If you want to disable this feature, you can turn it off by simply setting isSanitizationEnabled to false.

The Following lists the four newly added configurations:

isSanitizationEnabled: The flag that specifies whether sanitization of inbound request payload should be done. When enabled, the new validation mechanism will get triggered, which validates the request and only allows the one which adheres to WhiteListSchemes and WhiteListDomains properties.
WhiteListSchemes: The permitted schemes. The following schemes are permitted: http, https, ftp, sftp. These values are set in the wc-server and can be updated accordingly.
WhiteListDomains: The comma separated list of allowed domain, xml.cxml.org is the only allowed domain. These values are set in the wc-server and can be updated accordingly.
isLocalEntityEnabled: The flag is used during the entity resolution. When enabled, the parser will try to find and resolve the entity locally before trying to resolve the Uniform Resource Identifier (URI).

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 HCL 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 HCL 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 HCL 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 HCL 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 HCL 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>