Create an inbound XML message

In addition to the supported XML and WebSphere Commerce messages, we can add support for new inbound messages.

There are two primary methods for adding new inbound messages.

The recommended method is to add a new inbound XML message through the use of the user_template.xml inbound message template definition file. In this file, we can indicate the controller command the new inbound message invokes, define the elements of the message, and indicate the command parameters to which each element corresponds. When the message is received, the XML message mapper identifies the command to be run and the parameters to be used. The command is then invoked using the Site Administrator authority. For security reasons, ensure that only authorized persons can access and modify the user_template.xml message template definition file, otherwise unauthorized users would have the ability to write a new inbound message and invoke any WebSphere Commerce command as Site Administrator.

If you do not want to use the inbound XML message template definition files together with the XML message mapper, we can also implement the NewInboundMessage command to add new messages. This command is invoked when the message mapper does not recognize the message as an existing legacy message, or as an XML message defined in the inbound XML message template definition files. Since the NewInboundMessage command is not pre-programmed, you have full control over the processing that takes place once it is invoked. However, this method requires considerable programming effort, particularly where there are a large number of new messages.

WebSphere Commerce allows us to modify or extend the functionality of all inbound messages by modifying the WebSphere Commerce controller command that is run by each message. We can provide additional pre-processing or post-processing statements to any inbound message command used, or we can override the existing processing entirely. To do this, you need to have a knowledge of Java programming. When an inbound message is received from a back-end system, its information is processed into command parameters and a WebSphere Commerce controller command is invoked along with all the provided parameters. When the command is run, the performExecute() method is invoked, which in turn invokes three methods, in the following order:

1. doPreProcess()

2. doProcess()

3. doPostProcess()

When you first install WebSphere Commerce, only the doProcess() method contains programming statements. We can add pre-processing statements by extending the command and implementing the doPreProcess() method, or we can add post-processing statements by implementing the doPostProcess() method. Alternatively, we can implement either the doProcess() or the performExecute() method to overwrite the entire process.

Complete the following steps to add support for a new inbound message:

1. Define a DTD for the new XML message and save in the following directory:

   • (Developer) workspace_dir/WC/xml/messaging

   We can use the DTD files for existing XML messages as a guide. These files are located in the XML configuration directory.

   For example,

   <!ELEMENT Update_First_Element (DataArea)>
   <!ATTLIST Update_First_Element
    version CDATA #FIXED "1.0">
   <!ELEMENT DataArea (ABC)>
   <!ELEMENT ABC (#PCDATA)>

2. Add a new DTD file to the system, by doing one of the following:

   1. Place the DTD file you created for the new message in the same directory as your other messaging DTD files. The files are stored in the following directory:

      • (Developer) workspace_dir/WC/xml/messaging

   2. (Developer) Add the name of inbound message DTD files under the Messaging/EcInboundMessageDtdFiles tag found in the WebSphere Commerce configuration file.

3. Create a new controller command or customize an existing task command to handle a message with a certain message ID or name. For example,

   <?xml version='1.0' encoding='UTF-8'?>
   <!DOCTYPE Update_First_Element SYSTEM 'Update_New_Message.dtd'>
   <Update_First_Element version='1.0'>
   <DataArea>
   <ABC>123456</ABC>
   </DataArea>
   </Update_First_Element>

4. Update the user_template.xml inbound message template definition file for the new message. For example,

   <?xml version='1.0' encoding='UTF-8'?>
   <!DOCTYPE ECTemplate SYSTEM 'ec_template.dtd' >
   <ECTemplate>
   <TemplateDocument>
   <DocumentType version='1.0'>Update_First_Element</DocumentType>
   <StartElement>Update_First_Element</StartElement>
   <TemplateTagName>NewMessageMap</TemplateTagName>
   <CommandMapping>
   <Command CommandName='NewCommand' />
   </CommandMapping>
   </TemplateDocument>
   <TemplateTag name='NewMessageMap'>
   <Tag XPath='DataArea/ABC' Field='ABC_id' />
   </TemplateTag>
   </ECTemplate>

Related concepts
Inbound message template definition files