Ranking list framework for marketing actions

The ranking list framework for marketing actions enables the tracking of customer storefront actions. For example, by default, WebSphere Commerce tracks the number of times products are purchased and categories are viewed.

Activity templates

Four new activity templates are added to the New Activity From Template dialog to support the ranking list framework for marketing actions:

Display Best Sellers
Display Top Browsed
Display Recently Viewed Products
Display Recently Viewed Categories

For more information, see Creating a web activity.

Campaign element task commands and template parameters

Each trigger, target, and action has an associated task command called a campaign element task command. The task command performs the work associated with the campaign element. The campaign element template definition must specify which task command to use.

The validateParameters method validates the campaign element's parameters when the marketing activity is activated. It validates that the business user set all the required name-value pairs for the campaign element in the user interface, and can return error messages to the business user. You can use other methods in the validateParameters method to help validate the campaign element, for example, validateCategory or validateProduct.

For example, if extending DisplayProductRankingActionTaskCmdImpl, the validateCategory method in DisplayProductRankingActionTaskCmdImpl.validateParameters is called to check that the objectGroupId is a valid category.

For more information, see Campaign element task commands.

The following special element name-value pairs can be defined to specify that a campaign element should be processed by the SendMarketingTriggers scheduled job:

repeatSchedule: Indicates that the campaign element should be processed by the SendMarketingTriggers scheduled job. The method forwardTriggersForProcessing will be called on the campaign element task command. A value of runDaily sets that the processing should occur every day. A value of runOnce sets that the processing should only happen the first time the SendMarketingTriggers scheduled job runs after the activity becomes active and the current time is past the activity start date.
rankingBasedOnOrders: Indicates that this campaign element is for a best sellers list, and that the data in the campaign element should be used when an order has been placed to create the appropriate entries in the DMRANKINGSTAT database table.

For more information, see Campaign element template parameters.

New actions shipped with Management Center

The following actions are shipped with Management Center to support the ranking list framework for marketing actions:


Action name in Management Center	Campaign element template name	Campaign element task command	Command name to match in the behavior rule
Display Best Sellers	ranking_MostSold	DisplayProductRankingActionTaskCmd	none
Display Top Browsed	ranking_MostBrowsed	DisplayProductRankingActionTaskCmd	ProductDisplay

For more information, see List of shipped campaign element templates and task commands.

Business policies and ranking lists

Both the best sellers and top browsed actions use a business policy that evaluates the gathered statistics and generates the ranking lists. Customizing and creating a new ranking list for other business objects, top 10 search terms, is also achievable. One option is for the customization to populate the DMRANKINGSTAT table with the appropriate statistics of the search events, and use the provided ranking policy to evaluate the statistics. However, if the provided ranking policy is not applicable to the customization scenario, either a custom business policy can be created, or the provided policies configured with different parameters.

A business policy is used to define how to generate rankings. A ranking type relates to a ranking policy that contains two BusinessPolicyCommands. One command is to cleanup and summarize the ranking statistic data. This command's purpose is to delete out-of-date data that is no longer required and to summarize data into less database rows, helping control the size of the DMRANKINGSTAT statistics table. The cleanup command must implement the CleanupRankingPolicyCmd interface. The other command is to evaluate the statistics data and generate the ranking list. This command's purpose is to analyze the existing statistics and populate the DMRANKINGITEM database table. The generate command must implement the GenerateRankingPolicyCmd interface.

Each ranking campaign element template must define which policy it uses in the policyId argument in the campaign element template implementation definition.

To add a new ranking policy:

Develop a ranking generate policy command.
The process of how to generate a ranking list is implemented as a BusinessPolicyCommand. The business policy command should extend the AbstractGenerateRankingPolicyCommandImpl class that implements the GenerateRankingPolicyCommand interface. The following methods must be provided:

preGenerate()

Sets up the command parameters.

generate()

Generates the ranking list.

postGenerate()

Adjusts the generated ranking list.

The following diagram illustrates the process:
Develop a ranking data cleanup policy command.
The process of how to cleanup ranking statistics is implemented as a BusinessPolicyCommand. The business policy command should extend the AbstractCleanupRankingPolicyCommandImpl class that implements the CleanupRankingPolicyCommand interface. The following methods must be provided:

cleanup()

Cleans up out-of-date data and summarizes the existing data to reduce the number of entries in the statistics table.

The following diagram illustrates the process:
Register the ranking policy.
The new business policy must be of type Ranking. The parameter for each policy is defined in properties as a list of name-value pairs separated by an ampersand & symbol. The following code is an example of a policy definition:
```
<policy policy_id="10001" policyname="SalesRankingPolicy" policytype_id="Ranking" storeent_id="10010" properties="ObjectType=0" />
```
The generate and cleanup policy commands must be also configured. The following code is an example of a policy command definition:
```
<policycmd policy_id="10001" businesscmdclass="MyGenerateRankingPolicyCmdImpl" />
<policycmd policy_id="10001" businesscmdclass="MyCleanupRankingPolicyCmdImpl" />
```

The following customization tasks can be reused to provide rankings of other business objects:

Use the Marketing services to detect if the object is accessed or browsed. This detection is achieved by defining the appropriate behavior rule for the new campaign element. For more information, see Behavior rule definition.
Use the Marketing services to record the statistics. This is achieved by putting the appropriate policyId in the campaign element parameters:
```
<Argument name="policyId" value="XXX"/>
```
The policy parameters defines a new ObjectType for the new type of business object that is being ranked:
```
properties="ObjectType=X"
```
Where 0= best sellers, and 1= top browsed.
Typically, use the existing policy commands:
- CleanupProductRankingPolicyCmdImpl
- GenerateProductRankingPolicyCmdImpl

Displaying the count totals in ranking lists

To display the actual count that is associated with each product in the ranking list, that is, the number of times the product was browsed, or the number of times the product was purchased, in the specified time frame, add the following snippet to the e-Marketing Spot JSP file snippet for each catalog entry to display the associated amount:


${marketingSpotData.properties['amount']}

Daily updates for best sellers

When you are creating Web Activities that include best sellers, the order data is analyzed and the best sellers list is updated once per day, where the update time is configurable in the wc-admin-component.xml file:

<_config:property name="dailyScheduledJobTimeForTriggers" value="hh:mm"/>

Where:

hh = two digits, which represent the hour (00 - 23)
mm = two digits, which represent the minute (00 - 59)

At the configured time, the best sellers list is updated for the categories specified in any best sellers action for all the currently active activities. This setting should be configured to be at an off-peak time of the site.

Caching strategy for best sellers

As the best sellers list is only updated once per day, it is highly recommended that the e-Marketing Spot JSP file snippet that display the best sellers list is cached by using dynamic caching.

For example, a dependency ID, RankingEMarketingSpot, is issued when the InvalidateRankingServletCmdImpl command is called. This ID causes the JSP file to refresh when the list is updated. The invalidate command is called once per day after the best sellers lists are updated:

<cache-entry>
    <class>servlet</class>
    <name>/AuroraESite/Snippets/Marketing/RightSidebarRankingESpotDisplay.jsp</name>
    <property name="do-not-consume">true</property>
    <property name="save-attributes">false</property>
    <cache-id>
     <component id="emsName" type="parameter">
       <required>true</required>
     </component>
     <component id="categoryId" type="parameter">
<required>true</required>
</component>           
         <component id="DC_storeId" type="attribute">
<required>true</required>
</component>
<component id="catalogId" type="parameter">
<required>true</required>
</component>
<component id="categoryId" type="parameter">
<required>true</required>
</component>
<component id="pageView" type="parameter">
<required>false</required>
</component>
<component id="currentPage" type="parameter">
<required>false</required>
</component>
<component id="DC_lang" type="attribute">
<required>true</required>
</component>
<component id="DC_curr" type="attribute">
<required>true</required>
</component>
<component id="DC_cont" type="attribute">
<required>true</required>
</component>
<component id="DC_mg" type="attribute">
<required>true</required>
</component>
    </cache-id>

<dependency-id>RankingEMarketingSpot</dependency-id>
<dependency-id>dialogMarketingJsp</dependency-id>

</cache-entry>


<cache-entry>
 <class>command</class>
 <name>com.ibm.commerce.marketing.commands.ranking.InvalidateRankingServletCmdImpl</name>
 <invalidation>RankingEMarketingSpot</invalidation>
</cache-entry>

For more information, see Dynamic caching.

Extended Sites rankings

If an activity that contains the best sellers action is defined in a Storefront Asset Store, a separate best sellers list is created for each Extended Site store that refers to the Storefront Asset Store. That is, the best sellers lists of each storefront contains their individual storefront's order data to compile the rankings.

Configuration of best sellers rankings

If the best sellers action is being used, the ExperimentEvaluationEventListener must be enabled:


<component compClassName="com.ibm.commerce.marketingcenter.events.runtime.ExperimentEvaluationECEventListenerImpl"
      enable="true" name="Experiment Evaluation Event Listener">
      <property display="false">
        <start enabled="true"/>
      </property>
    </component>

To create the best sellers list, statistics of events are recorded in the DMRANKINGSTAT database table. These events are first recorded in memory, and are later persisted in a batch insert to achieve optimum performance. The size of the data that is recorded in memory is controlled by the userBehaviorBatchUpdateCacheSize parameter of the wc-admin-component.xml file.

For more information, see Promotion component configuration file (wc-admin-component.xml).

The following database tables support this feature:

DMRANKINGSTAT: This table stores collected information that is used to generate a ranking list. For example, when a relevant product is purchased or browsed, the data is recorded in this table.
DMRANKINGITEM: This table stores calculated ranking information. For example, the top 10 products purchased in a category, or the top 5 browsed products in a category. Each ranking item under a ranking group contains a sequence.

Configuration of top browsed rankings

Top browsed ranking lists display the most browsed products in a category.

If the top browsed action is being used, the SensorEventListener must be enabled:


<component compClassName="com.ibm.commerce.marketing.dialog.trigger.SensorEventListener"
      enable="true" name="SensorEventListener">
      <property display="false">
        <start enabled="true"/>
      </property>
    </component>