Adding messages to the Listener for IBM MQ

WebSphere Commerce allows you to extend the Listener for IBM MQ (formally transport adapter) to process additional messages.

About this task

Adding messages involves doing the following:

  • Creating an XML template of the message.
  • Mapping the message to a controller command.

To do this, you will need to have an advanced knowledge of XML, and of the WebSphere Commerce controller commands. If your message requires you to create a new controller command, you will also need to have an advanced knowledge of the WebSphere Commerce database schema, and Java programming.


  1. Create a DTD file to be used for parsing the inbound message and put it the following directory:
    • WC_installdir/wc.ear/xml/messaging
    • WebSphere Commerce Developer workspace_dir/wc/xml/messaging
  2. Add it to the tag of Messaging attribute, ECInboundMessageDtdFiles, in the WebSphere Commerce configuration file:
    EcInboundMessageDtdFiles="NCCommon.mod, NCCustomer_10.mod, 
    Create_NC_Customer_10.dtd, Update_NC_Customer_10.dtd, Update_NC_OrderStatus_10.dtd, 
    Update_NC_ProductInventory_10.dtd, Update_NC_ProductPrice_10.dtd, Create_WCS_Customer_20.dtd, 
    Update_WCS_Customer_20.dtd, Update_WCS_OrderStatus_20.dtd, Update_WCS_ProductPrice_20.dtd, 
    Inquire_WCS_PickPackListDetail_10.dtd, Create_WCS_PickBatch_10.dtd, Create_WCS_ExpectedInventoryRecord_10.dtd, 
    Create_WCS_InventoryReceipt_10.dtd, Update_WCS_InventoryReceipt_10.dtd, Create_WCS_ShipmentConfirmation_10.dtd, 
    Update_WCS_ProductInventory_20.dtd, Request_WCS_BE_ProductInventory_10.dtd, Update_WCS_OrderStatus_30.dtd, 
    Update_WCS_PriceAndAvailability_10.dtd, Update_WCS_ShoppingCartTransfer_10.dtd, Update_WCS_BatchAvailability_10.dtd, Update_New_Message.dtd"
  3. Create a mapping file to map the message content to the command name and needed parameters in the user message template file. The initial template can be found in the following directory:
    • WC_installdir/wc.ear/xml/messaging/user_template.xml
    • WebSphere Commerce Developer workspace_dir/wc/xml/messaging/user_template.xml.
  4. To add new messages, continue with the following:
    • Create a new controller command (interface and implementation) to execute the needed business logic. For example
    <action-mappings type="">
     path="/NewCreation" type="">
     <set-property property="authenticate" value="0:0"/>
     <set-property property="https" value="0:1"/>
    For more information about creating views, see Representing view implementations: action-mappings and global-forwards.
  5. If you are overriding existing command implementation, add or update the corresponding row in the CMDREG table, and assign a proper class name mapping to the correct interface name. If a response is required, add a forward view as well for devicefmt_id of -2000. For example,
    <forward className=""
    name="NewCreationRedirectView/0/-20000" path="/NewCreation.jsp">
    <set-property property="resourceClassName" value=""/>
    <set-property property="properties" value="storeDir=no"/>
    <set-property property="interfaceName" value=""/>
    <set-property property="implClassName" value=""/>
    <set-property property="direct" value="true"/>
  6. If the site is under development, you can add the DebugMode="true" attribute to the Messaging tag. Any changes in the DTD files will be loaded during the next inbound message. Step 8 will be required if the DTD was first added to the DTD file list above.
  7. For IBM i OS operating systemAIXLinuxWindowsUse WebSphere Application Server Administration Console to update the EAR and the Stores.war file.


    • The NewCreation.jsp generates the response message. This JSP file should be updated using the WebSphere Administration Console to the WC_eardir/Stores.war directory.
    • If the default directory "messaging" is not used, additional directory can be created relative to WC_eardir/xml. At runtime, WAS classloader will attempt to load these files by pre-pending this directory "messaging" or the newly created directory to the DTDs or mapping template file before loading. By default, XML configuration directory is added to the application's classpath. Any new directory under this XML configuration directory can be loaded by the classloader.
  8. Restart the WebSphere Commerce Server.


The following are samples you can follow:

Sample message:

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

Sample DTD file:

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

Sample user_template.xml:

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