Adding messages to the Listener for IBM MQ

HCL 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 HCL 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 HCL Commerce database schema, and Java programming.

Procedure

Create a DTD file to be used for parsing the inbound message and put it the following directory, workspace_dir/wc/xml/messaging

Add it to the tag of Messaging attribute, ECInboundMessageDtdFiles, in the HCL Commerce configuration file:


<Messaging 
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"
EcInboundMessageDtdPath="messaging"
EcMimePropFile="lang_mime.data"
EcSystemTemplateFile="sys_template.xml"
EcTemplatePath="messaging"
EcUserTemplateFile="user_template.xml"
XMLWebControllerUserId="wcsadmin" 
/>

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 workspace_dir/WC/xml/messaging/user_template.xml

To add new messages, create a new controller command (interface and implementation) to execute the needed business logic.

For example, for HCL Commerce Version 9.0.0.x:


<action-mappings type="com.ibm.commerce.struts.ECActionMapping">
.... 
 <action
 parameter="com.ibm.companyA.NewCreationCmd"
 path="/NewCreation" type="com.ibm.commerce.struts.BaseAction">
 <set-property property="authenticate" value="0:0"/>
 <set-property property="https" value="0:1"/>
 </action>
....
</action-mappings>

In Version 9.0.1+, you would use code like the following:

<action class="com.ibm.commerce.struts.v2.BaseAction" name="NewCreation"> 
<param name="authenticate">0:0</param> <param name="https">0:1</param> 
<param name="parameter">com.ibm.companyA.NewCreationCmd</param>
</action>

For more information about creating views, see Representing view implementations: action-mappings and global-forwards.

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, do the following:

For HCL Commerce Version 9.0.0.x installations: Add a forward view as well for devicefmt_id of -2000. For example,


<global-forwards>
...
<forward className="com.ibm.commerce.struts.ECActionForward"
name="NewCreationRedirectView/0/-20000" path="/NewCreation.jsp">
<set-property property="resourceClassName" value="com.ibm.commerce.messaging.viewcommands.MessagingViewCommandImpl"/>
<set-property property="properties" value="storeDir=no"/>
<set-property property="interfaceName" value="com.ibm.commerce.messaging.viewcommands.MessagingViewCommand"/>
<set-property property="implClassName" value="com.ibm.commerce.messaging.viewcommands.MessagingViewCommandImpl"/>
<set-property property="direct" value="true"/>
</forward>
...
</global-forwards>

Add a result for the struts action. For example,

<action class="com.ibm.commerce.struts.v2.BaseAction" name="NewCreation">
<param name="authenticate">0:0</param>
<param name="https">0:1</param>
<param name="parameter">com.ibm.companyA.NewCreationCmd</param>
<result name="NewCreationRedirectView">
<param name="location">/NewCreation.jsp</param>
<param name="resourceClassName">com.ibm.commerce.messaging.viewcommands.MessagingViewCommandImpl</param>
<param name="interfaceName">com.ibm.commerce.messaging.viewcommands.MessagingViewCommand</param>
<param name="implClassName">com.ibm.commerce.messaging.viewcommands.MessagingViewCommandImpl</param>
<param name="properties">storeDir=no</param>
<param name="direct">true</param>
</result>
</action>

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.
Use WebSphere Application Server Administration Console to update the EAR and the Stores.war file.
Notes:
- 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.

Results

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'>
<DataArea>
<ABC>123456</ABC>
</DataArea>
</Update_First_Element>

Sample DTD file:


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

Sample user_template.xml:


<?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>