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.

Whenever an inbound XML message is passed to the message mapper, it checks to see if the message is defined in the template definition files. If so, it retrieves the WebSphere Commerce controller command name and parameter names for the message, and parses the incoming message to get the values for the parameters. Once the message has been parsed, the message mapper returns a CommandProperty object containing the command name and the parameter name-value pairs for the command.

There are two template definition files provided by WebSphere Commerce.

sys_template.xml

The template definition used to map existing WebSphere Commerce inbound XML messages. The sys_template.xml file contains the outline of all inbound XML messages supported by WebSphere Commerce. The file defines the data fields for each message, mapping the message to the appropriate WebSphere Commerce Controller Command, and mapping each field within the message to the appropriate parameter for that command. The structure of sys_template.xml is based on the ec_template.dtd file, which defines the format that messages must take.

user_template.xml

The template definition we use to enable you to add additional inbound XML messages. The user_template.xml is an XML message template definition file that allows us to add new inbound XML messages to be supported by your system. An outline should be added to this file for each new XML message to support. We can use the sys_template.xml file as a guide on how to use or update this template file.

The outline should indicate the tag template to be used, the element from which the tag mapping should be started, the name of the WebSphere Commerce controller command to be invoked, and the URL parameters that correspond to each XML element.

Before you add any of our own messages, ensure the file contains the following lines:

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE ECTemplate SYSTEM 'ec_template.dtd' >
<ECTemplate>
</ECTemplate>

Both files are in XML format, based on the ec_template.dtd DTD file. The ec_template.dtd file contains the blueprint for all inbound messages outlined in the sys_template.xml file, and should be used to guide you in the creation of any new messages in the user_template.xml file.

The message template definition files are used to define the XML parsing information for the inbound XML message. Each message defined in these files has the following two base elements:

TemplateDocument

Defines the DTD file used by the message, the command called when the message is received, which tag mapping is to be used, and the XML element from which tag mapping is started.

TemplateTag

Defines the mapping of XML elements in the DTD file to parameter names of commands in WebSphere Commerce. The template tag element identifies the parameter names and tells the message mapper where to find the values on an incoming message.

By default, all of the template definition, template definition DTD, and DTD files for inbound XML messages are stored in the XML configuration directory in the messaging subdirectory.

Important: For security reasons, ensure that only authorized persons can access and modify the sys_template.xml and the user_template.xml message template definition files. If unauthorized persons have access to write to this file, they would have the ability to write new inbound messages that could invoke any WebSphere Commerce command as a Site Administrator.

Related concepts
Message mappers

Related tasks
Creating an inbound XML message