Customizing analytics data for non-Web channels with Coremetrics for WebSphere Commerce Sales Center

Document options Document options requiring JavaScript are not displayed Rate this page Help us improve this content

Level: Intermediate

Priyajith Chembakassery (priyajith@in.ibm.com@us.ibm.com), Software Developer, IBM
Sailatha Karthikeyan (saikarth@in.ibm.com@us.ibm.com), Software Developer, IBM

12 Dec 2007

The integration of Sales Center with Coremetrics in WebSphere® Commerce V6 provides multi-channel reports specific to the WebSphere Commerce environment that enable you to analyze user behavior across various channels. This article explains how to customize the data sent to Coremetrics for analysis from non-Web channels of WebSphere Commerce.

Introduction

The default approach used by Coremetrics to capture data for analytics is a Web-based solution using the JavaScript tagging functions. This approach doesn't work with non-Web channels like Sales Center or Gift Center, as these are standalone applications. In order to integrate standalone applications like the Sales Center with Coremetrics, a solution was developed based on the business event infrastructure provided by WebSphere Commerce (hereafter called Commerce) and Web services.

The event infrastructure persists the event data generated through non-Web channels in an internal Common Business Event (CBE) format specific to Commerce. For the integration, the event data in the internal CBE format has to be transformed to a format that can be directly consumed by Coremetrics. A set of mapping definition XML files are used to perform this transformation. The mapping XML files define the operations to be performed on the internal CBE XML. For transforming the event data, the XPath is used to locate the nodes to be modified in the internal CBE XML, and a custom framework in Commerce performs the XML DOM manipulation to map the data from the internal CBE format to the external format. The transformed XML is sent to Coremetrics servers using either Web services or a custom file transfer mechanism.

In this article, you'll learn how to customize the analytics data generated from non-Web channels of Commerce to be sent to Coremetrics, using Sales Center as an example of non-Web channel. The Sales Center integration with Coremetrics requires WebSphere Commerce V6 with Feature Pack 2 installed and the "cm-salescenter" feature enabled. You should also have a working knowledge of XPath to fully understand the customization procedure.

Back to top

About the mapping definition XML files

The main purpose of the mapping definition XML files is to map the XML data from the Commerce-specific CBE format to an external CBE format that Coremetrics understands.

For the Sales Center Integration, we use the data captured from the following business events:

1. Member Create/Update
2. Order Creation
3. Order Item Creation
4. Order Item Update
5. Order Submission
6. Order Item Shipment
7. Order Cancellation

Each business event has a corresponding mapping XML defining the transformation operations. For example, the Order Creation event data uses mapOrderCreation.xml to transform the internal format to external. The default mapping XMLs are all located in the <EAR>/xml/config/bi directory. Along with mapping xml files, there is also a mapCommonEvents.xml that is used to modify the nodes that are part of the events.

The custom framework provided by Commerce can perform the following operations on the internal CBE based on the mapping definition XML files:

1. Insertion of a new node, before or after an existing node, that matches the XPath expression
2. Removal of the node pointed to by the XPath expression
3. Replacement of a node with a new node that matches the XPath expression
4. Setting an attribute in the node pointed to by the XPath expression

In the following example, we'll change the attribute of a node in the internal CBE XML based on the mapping XML file. In the following snippet, CommonBaseEvent is the root and contextDataElements is its child node.

<contextDataElements name="com.ibm.commerce.context.base.BaseContext.storeId"> 
	<contextValue>10101</contextValue> 
</contextDataElements> 
 

To change the value of the name attribute of the contextDataElements node from com.ibm.commerce.context.base.BaseContext.storeId to storeId, you would use the following mapping in the mapping XML file:

<action type="setAttribute" path="/CommonBaseEvent/contextDataElements[
@name='com.ibm.commerce.context.base.BaseContext.storeId']"
name="name" value="storeId"/>
 

The resulting CBE XML looks like this:

<contextDataElements name="storeId">
	<contextValue>10101</contextValue>
</contextDataElements>
 

Back to top

Customizing the analytics data for Coremetrics

You can customize the data to be sent to Coremetrics by modifying instructions in the mapping XML files. Before making any changes, you need to understand the existing data structure of the internal CBE XML format. If a new piece of information has to pass along with the existing data set, you need to find out which event the data should fit in and where the new data will fit into the resulting XML.

Let's take a look at the Order Submission event to demonstrate how to customize the event XML data. Below is a sample snippet from the Order Submission event:

<CommonBaseEvent extensionName="OrderSubmission"
globalInstanceId="OrderSubmission:434324324" localInstanceId="26502"
priority="10" version="1.0.1"> 
    <contextDataElements name="eventRaiseTime">
	<contextValue>2007-01-11T03:37:20.047Z</contextValue> 
    </contextDataElements> 
    <contextDataElements Name="com.ibm.commerce.context.base.BaseContext.userId"> 
	<contextValue>2002</contextValue> 
    </contextDataElements> 
    <contextDataElements name="com.ibm.commerce.context.base.BaseContext.storeId"> 
	<contextValue>10101</contextValue> 
    </contextDataElements> 
. . . . . . . . . .   
    <extendedDataElements name="Order">
	<children name="id" type="long"> 
	    <values>12001</values> 
	</children> 
	<children name="time.updated" type="dateTime">
	    <values>2006-12-04T03:47:51.484Z</values> 
	</children> 
	<children name="time.placed" type="dateTime">
	    <values>2006-12-04T03:47:51.484Z</values> 
	</children>
	<children name="subTotal" type="string">
	    <values>631.45000</values>
	</children>
	<children name="shippingTotal" type="string">
            <values>21.20000</values>
	</children>
	<children name="currency" type="string">
	    <values>USD</values>
	</children>
	<children name="OrderItem">
	    <children name="id" type="long">
		<values>30001</values>
	    </children>
	    <children name="subTotal" type="string">
	    	<values>112.000</values>
	    </children>	
	    <children name="shippingTotal" type="string">
	    	<values>10.000</values>
	    </children>
	</children>
. . . . . . . . . .   
  </extendedDataElements> 
. . . . . . . . . .   
</CommonBaseEvent>

The default mapOrderSubmission.xml does not pass any payment-related information in the Order Submission data. If you want to pass payment-related information with the Order Submission data, you'll have to modify mapOrderSubmission.xml.

First you need to identify where you want to the new node for payment information. The best idea is to include the payment method as a child of the <extendedDataElements name="Order"> node. You use the node operation insertAfter to insert the new node after the last Order child node identified by the XPath /CommonBaseEvent/extendedDataElements[@name= 'Order']/children[last()].

To insert an empty node after the last child of <extendedDataElements name="Order"> in the external XML, specify the following in mapOrderSubmission.xml:

<!-- inserts a new node -->
<action type="insertAfter" path="/CommonBaseEvent/extendedDataElements[
@name='Order']/children[last()]">
    <children name="paymentMethod" type="string">
	<values>null</values>
    </children>
</action>
			

The execution of the instruction above by the XML DOM manipulation framework adds the paymentMethod to the resulting XML, as shown here:

<extendedDataElements name="Order">
    <children name="id" type="long"> 
	<values>12001</values> 
    </children> 
. . . . . . . . . .   
    <children name="paymentMethod" type="string"> 
	<values> null</values> 
    </children>
</extendedDataElements>
		

After adding the new node, you can replace the null value with the actual payment method. Here we assume that you have implemented a method named getPaymentMethod() in a class named com.example.bi.EventHelper, which returns the payment method as a String value for a particular order, as shown below:

public class EventHelper {

	public String getPaymentMethod(String orderId) {
	 . . . . . . . .
	}

}
			

The XML DOM manipulation framework allows you to invoke getPaymentMethod() by passing the orderId from the mapping XML files using the <javaCall> tag. To replace the paymentMethod node value with the return value of the getPaymentMethod function, you can use the following snippet in mapOrderSubmission.xml:

<!-- updates the node -->
<action type="replace" path="/CommonBaseEvent/extendedDataElements[
@name='Order']/children[@name='paymentMethod']/values/text()">
    <javaCall classname=" com.example.bi.EventHelper">
	<valueMethod name="getPaymentMethod">
	    <input path="/CommonBaseEvent/extendedDataElements[@name='Order']
	    /children[@name='id']/values/text()"/>
	</valueMethod>
    </javaCall>
</action>

The input to the getPaymentMethod is passed as a reference to a node value identified by an XPath expression. After the above operations are applied and assuming getPaymentMethod returns the string value COD, the resulting XML will look like this:

<extendedDataElements name="Order">
    <children name="id" type="long"> 
	<values>12001</values> 
    </children> 
. . . . . . . . . .   
    <children name="paymentMethod" type="string"> 
	<values>COD</values> 
    </children>
</extendedDataElements>

You've seen how to insert a new node using the XML node operations insertAfter and replace it with a specified value in the resulting XML. In a similar way, you can also use operations like delete to modify the internal CBE XML to customize data to meet your requirements.

The table below lists the functions supported by the WebSphere Commerce XML DOM manipulation framework to perform operations on the internal CBE XML format.

Back to top

Conclusion

In this article, you learned how to customize the mapping definition XML files used in the sending of the analytics data from a non-Web channel to Coremetrics. Using this knowledge, you can change the default data set based on your requirements to better leverage the analytics services provided by Coremetrics for efficient performance of various business operations of WebSphere Commerce.

Resources

• Coremetrics Web site: Learn more about Coremetrics.
  
  
• WebSphere Commerce Sales Center Reports in Coremetrics (WebSphere Commerce V6 Information Center): This topic provides an overview of Sales Center Coremetric reports.
  
  
• WebSphere Commerce Feature Pack: Download the feature pack.

About the authors

		Priyajith Chembakassery is a Software Developer with the WebSphere Commerce Analytics team at the IBM India Software Lab. He is currently working with the Coremetrics integration with WebSphere Commerce. You can reach Priyajith at priyajith@in.ibm.com.

		Sailatha Karthikeyan is a Software Developer with the WebSphere Commerce Analytics team at the IBM India Software Lab. She is currently working with the Coremetrics integration with IBM WebSphere Commerce. You can reach Sailatha at saikarth@in.ibm.com.

Rate this page

Please take a moment to complete this form to help us better serve you. Did the information help you to achieve your goal? Yes No Don't know   Please provide us with comments to help improve this page:   How useful is the information? 1 2 3 4 5 Not useful Extremely useful

Back to top