Ways to inform the marketing services of external or custom events for triggers and targets

Certain triggers and targets in marketing activities must detect events. You might want to create a custom trigger or target that detects a custom event, or an event that occurs on a system that is external to WebSphere Commerce. If so, you can call the Process MarketingTrigger service to inform the marketing services that the event occurred. You can call this service a number of ways, by using a URL or by using Java code.

WebSphere Commerce can detect events that match existing WebSphere Commerce URL requests or WebSphere Commerce commands, such as when a customer views a category display page or registers. In these situations, you need to define only a behavior rule in the campaign element template to detect the event. The marketing services handle the call to the Process MarketingTriggers service.

WebSphere Commerce cannot detect custom events or external events without customization. A custom event on the storefront might be when a customer clicks a custom link on a store page. An external event might be when a customer reviews a product. To detect custom or external events, you must choose one of the following methods to call the Process MarketingTriggers service. When the marketing services process the service call, they either pass the customer to the next element in the activity flow or record the behavior defined in the campaign element.

To inform the marketing services of the custom or external event, pass the marketing services the name of your event by using the DM_ReqCmd parameter in the Process MarketingTriggers service call.

  • For a custom trigger or target, the DM_ReqCmd parameter value must match the command name specified in the behavior rule definition for your custom trigger or target campaign element.
  • If you are detecting an event for the Wait For Event trigger, the DM_ReqCmd parameter value must match the event name that is entered in the properties view for the Wait For Event Trigger in the Management Center Marketing tool.

You can include any other name-value pairs in the Process MarketingTriggers service call.

Ways to call the Process MarketingTrigger service Details
Through a URL

Call either the MarketingTriggerProcessServiceEvaluate URL or the AjaxMarketingTriggerProcessServiceEvaluate URL.

Provide full URLs, as shown in this example service call:

http://hostname/webapp/wcs/stores/servlet/AjaxMarketingTriggerProcessServiceEvaluate?
DM_ReqCmd=CustomFraudDetectedTriggerEvent&eventType=CreditCard&storeId=10001&storeId=10001
Note:
If the URL is being called from a store page, then storeId is already on the URL and does not need to be added. If the URL is from an external site, then storeId is required.

For the URL MarketingTriggerProcessServiceEvaluate, include a redirect URL value, as shown in this example service call:

http://hostname/webapp/wcs/stores/servlet/MarketingTriggerProcessServiceEvaluate?
DM_ReqCmd=CustomFraudDetectedTriggerEvent&eventType=CreditCard&
URL=TopCategoriesDisplay?storeId=10001&catalogId=10001
Using code Through the MarketingFacadeClient method evaluateMarketingTrigger(Map parameters).

The following code is an example of the service call:

    Map parameterMap = new HashMap();
    parameterMap.put("DM_ReqCmd", "MyCustomTrigger");
    parameterMap.put("param1", "I");
    parameterMap.put("param2", "B");
    parameterMap.put("param3", "M");
    marketingFacadeClient.evaluateMarketingTrigger(parameterMap);
OR

Through the MarketingFacadeClient method processMarketingTrigger(String action, Hashtable nvps, String triggerParameters).

The following code is an example of the service call:

marketingFacadeClient.processMarketingTrigger(
    MarketingFacadeConstants.PROCESS_VERB_ACTION_EVALUATE, 
    null, 
    MarketingUtilClient.createTriggerParametersString(
        null, 
        "CustomFraudDetectedTriggerEvent", 
        "eventType=CreditCard", 
        null, 
        null)
);

For more information about these methods, see MarketingFacadeClient.

Determining the customer's personalization ID for an external event

Marketing activities require the customer's personalization ID. If the event occurs on an external system that cannot pass the customer personalization ID, you need to map information that is known by the external system to the customer personalization ID in WebSphere Commerce. To accomplish this mapping, provide an implementation of the MarketingServicesTaskCmd that implements the method getPersonalizationId. This method maps from the external identifier of the customer to the WebSphere Commerce identifier for the customer (personalizationId). Then, register the task command in the CMDREG table.

The following code is an example of a task command for this purpose. In this example, the external system has the customer's phone number. The assumption is that the customer is registered in the WebSphere Commerce store and is provided the same phone number. This method finds the customer's personalization ID based on the provided phone number when the Process MarketingTrigger service is called and includes the parameter phone.

public class MyCompanyMarketingServicesTaskCmdImpl 
extends MarketingServicesTaskCmdImpl 
implements MarketingServicesTaskCmd {
	
	/**
	 * IBM copyright notice field.
	 */
	public static final String COPYRIGHT = com.ibm.commerce.copyright.IBMCopyright.SHORT_COPYRIGHT;
	/**
	 * The name of this class.
	 */
	public  static final String CLASSNAME = "com.mycompany.commerce.marketing.dialog.util.MyCompanyMarketingServicesTaskCmdImpl";
	private static final Logger LOGGER = LoggingHelper.getLogger(MyCompanyMarketingServicesTaskCmdImpl.class);
	
	/**
	 * This method will find a customer's personalization ID based on the provided phone number.
	 * @param triggerParameters: The trigger parameters passed in the service call. This should
	 * include a parameter named phone. The external system has the customer's phone number,
	 * and it is assumed that the customer has provided the same number in their WebSphere Commerce 
	 * account. This method maps the customer's phone number to their personalization ID.
	 * @return: The customer's personalization ID.
	 */	
	public String getPersonalizationId(StringBuffer triggerParameters) {
		final String METHOD_NAME = "getPersonalizationId";
		if (LoggingHelper.isEntryExitTraceEnabled(LOGGER)) {
			LOGGER.entering(CLASSNAME, METHOD_NAME);
		}
		String pznId = null;
		try {
			String phoneNumber = MarketingUtil.getDataFromTriggerParametersString(triggerParameters.toString(), "phone");
			if (LoggingHelper.isTraceEnabled(LOGGER)) {
				LOGGER.logp(Level.FINE, CLASSNAME, METHOD_NAME, "phoneNumber:" + phoneNumber);
			}
			if (phoneNumber != null) {
				
				List pznIdList = new ServerJDBCHelperAccessBean().executeParameterizedQuery(
						"select users.personalizationid from users, address where users.users_id = address.member_id and address.phone1 = ?",  
						new Object[]{ phoneNumber } );
				if (LoggingHelper.isTraceEnabled(LOGGER)) {
					LOGGER.logp(Level.FINE, CLASSNAME, METHOD_NAME, "pznIdList:" + pznIdList);
				}
				if (pznIdList != null && pznIdList.size() == 1) {
					List pznIdEntry = (List)pznIdList.get(0);
					pznId = pznIdEntry.get(0).toString();
				}
				if (LoggingHelper.isTraceEnabled(LOGGER)) {
					LOGGER.logp(Level.FINE, CLASSNAME, METHOD_NAME, "pznId:" + pznId);
				}
			}
		} catch (Exception e) {
			if (LoggingHelper.isTraceEnabled(LOGGER)) {
				LOGGER.logp(Level.FINE, CLASSNAME, METHOD_NAME, "Exception:" + e);
			}
			e.printStackTrace();
		}		
		if (LoggingHelper.isEntryExitTraceEnabled(LOGGER)) {
			LOGGER.exiting(CLASSNAME, METHOD_NAME);
		}	
		return pznId;
	}
}