Develop > Controller layer > Integrate with back-end systems and external applications > Inbound services > Message mappers
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 that contains 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 that you can use to enable you to add additional inbound XML messages. The user_template.xml is an XML message template definition file that allows you to add new inbound XML messages to be supported by the system. An outline should be added to this file for each new XML message that to support. 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 the 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 that is 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
Related information