Creating an inbound XML message

In addition to the supported XML and WebSphere Commerce messages, you 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, you 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, you must 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, you 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 you to modify or extend the functionality of all inbound messages by modifying the WebSphere Commerce controller command that is run by each message. You can provide additional pre-processing or post-processing statements to any inbound message command used, or you can override the existing processing entirely. To do this, you need to have a knowledge of Java programming.

When you first install WebSphere Commerce, only the doProcess() method contains programming statements. You can add pre-processing statements by extending the command and implementing the doPreProcess() method, or you can add post-processing statements by implementing the doPostProcess() method. Alternatively, you 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:
   • WC_installdir/wc.ear/xml/messaging
   • workspace_dir/wc/xml/messaging

   You 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:
      • WC_installdir/wc.ear/xml/messaging
      • workspace_dir/wc/xml/messaging
   2. Add the name of inbound message DTD files under the Messaging/EcInboundMessageDtdFiles tag found in the WebSphere Commerce configuration file.
   3. Open Configuration Manager.
      1. Select Instance Properties, then open the Messaging folder.
      2. In the Inbound Message DTD Files field add the name of your new DTD file to the end of the list, placing a comma before the new filename.
      3. Click Apply to save the changes.
      4. From the WebSphere Application Server Administration Console, stop then restart the instance.
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>

5. Update the EAR file XML configuration directory. For more information, see theWays to update application files topic.