Develop > Controller layer > Integrate with back-end systems and external applications > Inbound services

Create 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, 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. 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_INSTALL/wc.ear/xml/messaging

   • workspace_dir/wc/xml/messaging

   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)&gt;
   <!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 the other messaging DTD files. The files are stored in the following directory:

      • WC_INSTALL/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 the 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 re-start 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'?&gt;
   <!DOCTYPE ECTemplate SYSTEM 'ec_template.dtd' &gt;
   <ECTemplate&gt;
   <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. See theWays to update application files topic in the WebSphere Application Server Information Center for additional information.

Related concepts

Inbound message template definition files

XML configuration directory

+

Search Tips   |   Advanced Search