Behavior rule definition

The behavior rule definition is an optional XML fragment in a campaign element template definition. A behavior rule definition defines how to detect when a customer interacts with the store in a way that is related to the trigger, target, or action. For example, if a target requires a customer to search for "hats" or browse the Furniture category three times in the last week, then the target must have a behavior rule that defines how to detect that behavior.

Each occurrence of the behavior is called an event. When the marketing services detect the event defined in the behavior rule:

  • For a trigger, the marketing services are notified that the event occurred. In most cases, this event triggers the activity to start or continue.
  • For a target or an action, typically, the event is recorded. This way, the marketing services can track what a customer does to determine whether the customer meets the criteria defined in the target or action.

When to use a behavior rule definition

A campaign element needs a behavior rule definition in its template definition only if its function requires the marketing services to detect information that is associated with a customer's behavior. The following are examples of campaign elements that are provided by default that have a behavior rule definition: the Catalog Browsing Behavior target, the Online Behavior target, the Customer Registers trigger, Customer Participates in Social Commerce trigger, and the Display Recently Viewed action.

A campaign element does not need a behavior rule definition if its function relies on data other than a customer's behavior and that information exists elsewhere. For example, the Purchase History target does not have a behavior rule definition because a customer's purchase history data is captured in the Order Management subsystem.

Where behavior rule definitions are stored

Format of behavior rule definitions

Behavior rule definitions have a number of mandatory and optional parameters. The following example shows the full list of parameters:

<BehaviorRule 
   command= "COMMAND_TO_MATCH" 
   processOnCommandExit="true/false"
   action="send/record/custom" 
   comparison="MARKETING_comparison"
   caseSensitive="true/false"
   maxSize="MARKETING_numberOfTimes"
   maxTotalSize="MARKETING_numberOfTimes"
   relativeDays="MARKETING_daysOperator"
   numberOfTimesOperator="MARKETING_numberOfTimesOperator"
   callCmdOnMatch="BEHAVIOR_RULE_TASK_COMMAND"  
   processOnlyFromService="true/false"
   parentCategory="findAll"
   synonymMatch="true/false"
   >
   <Variable 
      name="VARIABLE1_NAME_TO_MATCH"
      value="VARIABLE1_CONTENT_TO_MATCH"
      type="TYPE_OF_VARIABLE1"
      comparison="MARKETING_comparison"
      doNotRecord="true/false"
   />
</BehaviorRule>

Parameters in behavior rule definitions

Each parameter that a behavior rule definition can contain, as shown in the previous format example, is described here.

The values of the following three parameters are typically specified directly in the behavior rule XML fragment:

command
Specifies how the marketing services detect the occurrence of an event related to the campaign element. You can specify events by using one of the following methods:
Method Details and examples
1. Specify the name of the command from a storefront URL. Examples of URL commands are CategoryDisplay and ProductDisplay. When a storefront URL is called, the marketing services check whether the URL command name matches the behavior rule command name. This check determines whether the rule applies to the current event. For example, for a target that detects a customer that is viewing a category display page, the parameter can resemble the following code.
command="CategoryDisplay"

Specifying an URL command to detect events is a better option than specifying a controller command. Pages are often dynamically cached. When a cache hit occurs, the controller command is not called, but the marketing services can still detect the event by the URL that is called.

A number of campaign elements that are provided by default match URL commands such as CategoryDisplay or ProductDisplay. If your site uses different URL commands, then these campaign elements do not work unless you specify your custom command names in the marketing component configuration file (wc-admin-component.xml). For more information about modifying this file, see Changing the name of commands used in behavior rule matching.
2. Specify the name of a controller command. Examples of controller commands are OrderProcessCmd or UserRegistrationAddCmd. For example, for a trigger that detects when a customer registers, the parameter can resemble the following code.
command="UserRegistrationAddCmd"
When the behavior rule specifies a controller command, and that command successfully exits, the marketing services handle the event. Some events are handled by a server controller command, and in some situations, that command might fail. Examples of these commands are the user registration command or the logon command. In these situations, the event must be detected only when the controller command successfully exits. If your behavior rule specifies a controller command, you must:
  1. Specify the value true for the processOnCommandExit parameter in the behavior rule.
  2. Register the controller command in the marketing component configuration file (wc-admin-component.xml). For more information about modifying this file, see Changing the name of commands used in behavior rule matching.
3. Specify the name of a command passed to the marketing services. An example is the command SocialCommerceInteraction specified for the trigger Customer Participates in Social Commerce and the target Social Commerce Participation. To inform the marketing services of an event that occurs outside of the WebSphere Commerce server environment, call the Process MarketingTrigger service. You can give the event any name you want. You then specify that name in the behavior rule and use the same name for the DM_ReqCmd parameter in the Process MarketingTrigger service call. For more information, see Informing the marketing services of an external event for a trigger or target.

A command value of * indicates that all commands should be checked for the associated name-value pairs. The command value can be a list of commands when there are multiple commands that are associated with the same behavior. For example, for searches, Web 1.0 stores use the CatalogSearchResultView command whereas Web 2.0 stores use the AjaxCatalogSearchView command. Therefore, the command value for search targets is "AjaxCatalogSearchView,CatalogSearchResultView".

For examples of commands that are used in behavior rules, see the tables in List of shipped campaign element templates and task commands. URL commands are store-specific.

processOnCommandExit
Optional: Specifies whether the event occurs when a controller command exits. Values can be true or false. The value relates to the previous command parameter:
  • If the command parameter is a page URL command, then this value is false.
  • If the command parameter is a controller command that must successfully exit, then this value is true.
action
(Required) Specifies what to do when the marketing services detect the event that is specified in the behavior rule. You can set one of the following valid values:
  • send: Forward the occurrence of this event to the marketing services to be processed. This value applies to triggers.
  • record: Forward the occurrence of this event to the marketing services so that the behavior is recorded for a customer. This value applies to targets and actions.
  • custom: Detect the occurrence of this event, but do not forward the event to the marketing services. When action=custom, a custom task command handles the processing of this event. Some customization scenarios might use this value to detect events but then record the data by using some other means.
  • (empty): Do not record the occurrence of this event, and do not forward the event to the marketing services. Leave the action parameter empty to simply evaluate if the current request matched the behavior defined in the behavior rule. For example, the Current Page target that is provided by default leaves the action parameter empty. This target checks to see whether the event occurred, such as whether a customer views a specific store page, but the event is not recorded.

The following parameters are optional, depending on the function of the campaign element. In many cases, the parameter values are references to user interface properties that business users specify when they set up a campaign element. Look for the values that start with MARKETING_ to indicate these parameter values. These values are stored as name-value pairs in the DMELEMENTNVP table.

comparison
(Optional). Defines how to compare the actual parameter values detected from the event with the values specified in the behavior rule. The comparison parameter is required only for campaign element values that match one of the following parameters:
  • A name-value pair, such as on a store page URL or in a cookie (variable type=NVP)
  • A name-value pair on an external site referring URL (variable type=REFERRALNVP)

For example, a target that detects a matching keyword search (q=television) or a matching cookie parameter (ZIPCODE=90210) must use the comparison parameter.

Typically, campaign elements that match parameters allow business users to specify the comparison option in the user interface. In these cases, the value of the comparison parameter references the name-value pair in the DMELEMENTNVP table, as shown in this example:
comparison="MARKETING_comparison"
To specify the comparison value directly in the behavior rule definition, you can use one of the following valid values:
= The specified value must be an exact match to the actual value.
end The specified value must match the end of the actual value string.
start The specified value must match the beginning of the actual value string.
contain The specified value must be contained in the actual value string.
> The specified value must be greater than the actual value.
< The specified value must be less than the actual value.
>= The specified value must be greater than or equal to the actual value.
<= The specified value must be less than or equal to the actual value.
!= The specified value must not be equal to the actual value.
any The specified value can match with any value in the actual name-value pair.
recordAll The specified value can match with any value in the actual name-value pair, and each individual value must be recorded in the user behavior.
If you require a different calculation to match the specified value with the actual value, create a custom task command that implements UserBehaviorRuleTaskCmd to implement the check. The method getReturnValue can return the value from the behavior rule that matches the actual value, when a match occurs. If the actual value does not match any of the specified values, the getReturnValue method returns null. For more information when you are implementing the task command, see UserBehaviorRuleTaskCmd.

In the behavior rule XML format example, notice that the comparison parameter can also be set for a variable defined within the <Variable> element. If so, that value overrides the comparison value for the <BehaviorRule> element. If no comparison parameter is set for the variable, the comparison value for the <BehaviorRule> element is used.

caseSensitive
(Optional). Indicates whether the matching of name-value pairs is case-sensitive or case-insensitive. Values are true and false. The default value is true.
maxSize
(Optional). For each value that can be matched in this behavior rule, this value is the maximum number of times the marketing services records a customer behavior that is associated with an event . Consider a behavior rule that matches a keyword search for "hats" and "shirts". If maxSize=4, then for each customer, the marketing services records up to four occurrences of searching for "hats" and up to four occurrences of searching for "shirts". For example, the Catalog Browsing Behavior target that is provided by default uses the maxSize parameter. The default value is 1.
Typically, campaign elements that use maxSize parameter allow business users to specify this number in the user interface. In these cases, the value of the maxSize parameter references the name-value pair in the DMELEMENTNVP table, as shown in this example:
maxSize="MARKETING_numberOfTimes"
maxTotalSize
(Optional). The maximum number of times the marketing services records a customer behavior in total. Consider a behavior rule that matches a keyword search for "hats" and "shirts". If maxTotalSize=4, then for each customer, the marketing services record up to four occurrences of searching for either "hats" or "shirts".
Typically, campaign elements that use maxTotalSize parameter allow business users to specify this number in the user interface. In these cases, the value of the maxTotalSize parameter references the name-value pair in the DMELEMENTNVP table, as shown in this example:
maxTotalSize="MARKETING_numberOfTimes"
The following table provides examples of how the maxSize parameter and the maxTotalSize parameter are used together for two campaign elements shipped with HCL Commerce:
Campaign element maxSize value maxTotalSize value
Recently Viewed action 1

This value means that each unique catalog entry or category that a customer views is recorded only one time so that there are no duplicates in the recently viewed list.

 5

This value means that a maximum of 5 catalog entries or categories in total that are recorded and display in the recently viewed list.
Social Commerce Participation target 5

This value means that each type of social commerce activity–a product review, or blog entry, or photo upload–is recorded up to 5 times for a customer.

 5

This value means that a customer must participate in social commerce a total of 5 times to meet the target criteria. Since the maxTotalSize value and the maxSize value are the same, the customer can do any combination of social commerce activities to reach a total of 5.

relativeDays
Optional: Specifies how many days relative to the current date the event must occur to meet the criteria of the campaign element. For example, for a target that requires a customer to browse the Furniture category "10 times in the last 3 days," the relativeDays parameter value is <=. This parameter prevents the marketing services from storing unnecessary data.
  • If the relativeDays parameter has a value, then the marketing services store only the most recent occurrences, up to the maxSize or maxTotalSize value.
  • If the relativeDays parameter does not have a value, then the marketing services record and store only the first occurrences, up to the maxSize or maxTotalSize value.
Typically, campaign elements that use the relativeDays parameter allow business users to specify this number in the user interface. In these cases, the value of the relativeDays parameter references the name-value pair in the DMELEMENTNVP table, as shown in this example:
relativeDays="MARKETING_daysOperator"
numberOfTimesOperator
Optional: Defines the relation between the specified maxSize or maxTotalSize value and the actual number of times the event occurred. For example, for a target that requires a customer to browse the Furniture category "less than 10 times," the numberOfTimesOperator parameter value is "<" (less than). If you are creating a target that is similar to the Online Behavior target shipped with Management Center, then include this parameter in your behavior rule.
Typically, campaign elements that use the numberOfTimesOperator parameter allow business users to specify the operator in the user interface. In these cases, the value of the numberOfTimesOperator parameter references the name-value pair in the DMELEMENTNVP table, as shown in this example:
numberOfTimesOperator="MARKETING_numberOfTimesOperator"

To specify the value directly in the behavior rule definition, you can specify one of the following valid values:

= Equals.
> Greater than.
>= Greater than or equal to.
< Less than.
<= Less than or equal to.
* Any number of times.

If the value is =, then the marketing services records up to the maxSize value plus one occurrence, to determine when the behavior exceeded the number of occurrences specified in the maxSize parameter. For example, the Catalog Browsing Behavior target uses this value.

callCmdOnMatch
(Optional). Specifies a task command to call custom processing of the event. The specified task command must implement BehaviorRuleTaskCmd. For example, if you want to record the top browsed products in a category; however, the marketing services currently record the events against individual customers. You want to use the marketing services to detect the product browse events, but you create a custom task command to record the browsing of each category in total for all the customers in the store.
processOnlyFromService
(Optional). Specifies that the event matches only when it is sent from a service call. The event does not match when the command name matches a URL command. For example, the Customer Checks Out with Promotion trigger relies on an internal event called OrderProcessFromOrderSubmission. This flag ensures that the event is detected only when an internal service call sends this event. Values are true and false. The default value is false.
parentCategory
(Optional). Specifies that when retrieving parent categories, all parent categories must be retrieved. The default behavior for campaign elements is to stop retrieving parent categories after the first match is found. The Display Top Browsed action uses this parameter to ensure that a browsed product is recorded against all its parent categories. The only valid value is findAll, which means retrieve all parent categories.
synonymMatch
(Optional). Specifies that during name-value pair comparisons, the search synonyms of the value are to be compared against the values specified in the behavior rule. This parameter is used for campaign elements that can match search synonyms, for example, the Customer Searches trigger and the Online Behavior target. Values are true and false. The default value is false.
Variable name-value type
(0 or more). Defines the name-value pairs to match from the event. A campaign element can match five types of events, which are described in the following table. Typically, a business user selects either the variable name, or the value, or both, in the user interface. In these cases, the variable parameter values reference the name-value pair in the DMELEMENTNVP table. The examples that are shown for each event to match in the following table use this method (look for the values that start with MARKETING_).
Event to match Variable format example and explanation
Match a name-value pair, for example, on a store page URL or in a cookie. Example: The existing Current Page target has the following variable that is defined in its behavior rule to match the product display page that a customer is currently viewing:
<Variable name="productId" value="MARKETING_catalogEntryIdList" type="NVP"/>

Where:

  • name: (Required) The name of the name-value pair to match.
  • value: (Required) The value of the name-value pair to match. The value * means that any value matches.
  • type: (Required) NVP
  • comparison: Optional: Defines how to compare the actual parameter values detected from the event with the values specified in the behavior rule. For supported values, see the comparison parameter definition
  • doNotRecord: Optional: Specifies whether to persist data that matches this variable to the user behavior database table (DMUSERBHVR). For usage details, see 1 at the end of this table.
Match a referring external site. Example: The existing External Site Referral target has the following variable that is defined in its behavior rule to match the referring site:
<Variable name="MARKETING_referralURLValue" value="MARKETING_equalsOrEndsWith" type="REFERRAL"/>

Where:

  • name: (Required) The domain of the external site.
  • value: (Required) The operator that describes how to match the actual referral URL to the specified referral URL value. Valid values include the following values:
    = The actual referral URL must match exactly the specified referral URL.
    end The actual referral URL must match the end of the specified value string for the referral URL.
    * Any referral URL matches.
  • type: (Required) REFERRAL
Match a name-value pair on an external site referring URL. Example: The existing External Site Referral target has the following variable that is defined in its behavior rule to match a name-value pair on the URL of the referring site:
<Variable name="MARKETING_urlName" value="MARKETING_urlValueList" type="REFERRALNVP"/>

Where:

  • name: (Required) The name of the name-value pair to match in the referral URL.
  • value: (Required) The value of the name-value pair to match in the referral URL. The value * means that any value matches.
  • type : (Required) REFERRALNVP
  • comparison: Optional: Defines how to compare the actual parameter values detected from the event with the values specified in the behavior rule. For supported values, see the comparison parameter definition.
  • doNotRecord: Optional: Specifies whether to persist data that matches this variable to the user behavior database table (DMUSERBHVR). For usage details, see 1 at the end of this table.
Match the parent category of a category or product parameter on a page URL Example: The existing Catalog Browsing Behavior target has the following variable that is defined in its behavior rule to match the specified parent category when a customer browsed a specific category display page: 
<Variable name="categoryId" value="MARKETING_categoryIdList" type="PARENTCATEGORY"/>

Where:

  • name: (Required) The name of the page URL parameter to match.
  • value: (Required) The value of the page URL parameter to match. The value * means that any value matches.
  • type: (Required) PARENTCATEGORY
  • comparison: Optional: Defines how to compare the actual parameter values detected from the event with the values specified in the behavior rule. Valid values include the following values:
    = The actual value must be an exact match to the specified value.
    != The actual value must not match the specified value. != can be used only if this variable has the doNotRecord parameter set to true.
  • doNotRecord: Optional: Specifies whether to persist data that matches this variable to the user behavior database table (DMUSERBHVR). For usage details, see 1 at the end of this table.
To check whether the current event matches the PARENTCATEGORY rule, the marketing services completes the following actions:
  • If the parameter productId is in the trigger parameters, the services check whether the product belongs to any of the categories specified in the behavior rule.

    Otherwise:

  • If the parameter categoryId is in the trigger parameters, the services check whether the category belongs to any of the categories specified in the behavior rule.
Match the date an event occurred Example: The existing Catalog Browsing Behavior target has the following variables that are defined in its behavior rule to match the date when a customer browsed a specific part of the store catalog:
<Variable name="MARKETING_beforeAfterOnDate" value="MARKETING_date1" type="CURRENTDATE"/>
<Variable name="MARKETING_beforeDate" value="MARKETING_date2" type="CURRENTDATE"/>

Where:

= on the exact date.
> before the date.
>= on or before the date.
< after the date.
<= on or after the date.
  • name: (Required) The operator that describes how the actual event date relates to the specified date. Valid values are:
  • value: (Required) The date to match.
  • type: (Required) CURRENTDATE
Table notes:
  1. Use the doNotRecord parameter to minimize the amount of data that is being recorded when your behavior rule contains more than one variable of these types: NVP, REFERRALNVP, and PARENTCATEGORY. By default, all variable data is persisted to the DMUSERBHVR table. By recording data for only one variable, you minimize performance impacts. Usage guidelines include the following guidelines:
    • Identify the variable that you want to record. If one of the variables can take multiple values (for example, manufacturer = AromaStar, Sharpson), choose this variable to record. If all of the variables take only a single value, it does not matter which variable you choose, but consider choosing the variable that is most relevant to the event that the behavior rule matches.
    • For the variable that you identified, set the doNotRecord parameter to false, or do not use this parameter.
    • For all other variables of the type NVP, REFERRALNVP, or PARENTCATEGORY, set the doNotRecord parameter to true.

    For an example of a behavior rule that uses the doNotRecord parameter, see the following generic trigger example.

  2. You can define a custom variable type if there are no events that match your requirements for a custom scenario. When you define a custom variable type, you must create a custom task command that implements the UserBehaviorRuleTaskCmd interface to implement the check. The getReturnValue method returns the value from the behavior rule that matches the actual value, if there is match. If the actual value does not match any of the specified values, the getReturnValue method returns null. For more information when you are implementing the task command, see UserBehaviorRuleTaskCmd.

Examples

The following code snippets show examples of XML fragments for behavior rule definitions:
  • Example XML fragment for a target that detects when a customer browsed a category a specific number of times (within an optional time frame).
    
<BehaviorRule 
   command="CategoryDisplay" 
   action="record" 
   maxSize="MARKETING_numberOfTimes" 
   relativeDays="MARKETING_daysOperator" 
   numberOfTimesOperator="MARKETING_numberOfTimesOperator">
   <Variable 
        name="categoryId" 
        value="MARKETING_categoryIdList" 
        type="NVP"/>
   <Variable 
        name="MARKETING_beforeAfterOnDate" 
        value="MARKETING_date1" 
        type="CURRENTDATE"/>
   <Variable 
        name="MARKETING_beforeDate" 
        value="MARKETING_date2" 
        type="CURRENTDATE"/>
</BehaviorRule>
  • Example XML fragment for a trigger that detects when a customer registers.
    
<BehaviorRule 
 command="UserRegistrationAddCmd" 
 processOnCommandExit="true"
 action="send" />
  • Example XML fragment for a target that detects when the current request has a specific name-value pair and then matches it (match is not case-sensitive).
    <BehaviorRule 
   command="*" 
   action="" 
   comparison="MARKETING_comparison"
   caseSensitive="false">
   <Variable 
        name="MARKETING_urlName" 
        value="MARKETING_urlValueList" 
        type="NVP"/>
</BehaviorRule>
  • Example XML fragment for a target that records the last n recently viewed categories.
    <BehaviorRule 
   command="CategoryDisplay" 
   action="record" 
   maxSize="1" 
   maxTotalSize="MARKETING_numberOfTimes" 
   comparison="recordAll" 
   relativeDays="yes">
   <Variable 
        name="categoryId" 
        value="*" 
        type="NVP"/>
</BehaviorRule>
  • Example XML fragment for a target that detects when the customer visits your site from a referring site (with an optional name-value pair on the referring URL).
    <BehaviorRule 
   command="*" 
   action="" 
   comparison="MARKETING_comparison" 
   caseSensitive="false">
<Variable 
        name="MARKETING_referralURLValue" 
        value="MARKETING_equalsOrEndsWith" 
        type="REFERRAL"/>
<Variable 
        name="MARKETING_urlName" 
        value="MARKETING_urlValueList" 
        type="REFERRALNVP"/>
</BehaviorRule>
  • Example XML fragment for a generic trigger that can be configured in the Marketing tool to detect specific events.
    <BehaviorRule
    command = "MARKETING_eventName"
    action = "record"
    comparison = "MARKETING_comparison"
    maxSize = "MARKETING_numberOfTimes"
    relativeDays = "MARKETING_daysOperator">
    <Variable
        name = "MARKETING_parameterOneName"
        value = "MARKETING_parameterOneValueList"
        type = "NVP"/>
    <Variable
        name = "MARKETING_parameterTwoName"
        value = "MARKETING_parameterTwoValue"
        type = "NVP"
        doNotRecord = "true"
        comparison = "="/>
    <Variable
        name = "MARKETING_beforeAfterOnDate"
        value = "MARKETING_date1"
        type = "CURRENTDATE"/>
    <Variable
        name = "MARKETING_beforeDate"
        value = "MARKETING_date2"
        type = "CURRENTDATE"/>
</BehaviorRule>