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 HCL 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.

HCL Commerce can detect events that match existing HCL Commerce URL requests or HCL 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.

HCL 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.

Table 1.
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) );`
Call the `event` REST API	You can inform the marketing services using the `Event` REST API. See Defining the event and parameters for a storefront event trigger via a custom marketing event URL or the marketing event REST API for more information. For Emerald, Sapphire, Ruby and other REST based stores: Call the `Event` REST API: `POST: https://<host>/wcs/resources/store/<storeId>/event Request Body: { DM_ReqCmd: "SubscribeToCategory", Category: "Furniture" }` In the example of registering a marketing event where shoppers enter the promo code `BLACKFRIDAY`, call the REST API as follows: `POST: https://<host>/wcs/resources/store/<storeId>/event Request Body: { DM_ReqCmd: "PromoCodeMarketingEvent", PromoCode: "BLACKFRIDAY" }` The name value pairs used in the `Event` API should be specified in the `Wait for Event` trigger in the marketing dialog activity created in the Management Center. As shown in the following example from the Management Center, `PromoCodeMarketingEvent` is specified in the `Event Name` field. The `PromoCode` is entered in the `Parameter name` field and `BLACKFRIDAY` is entered in the `Parameter value` field. For more information about the marketing event REST API, see ../../restapi/code91/marketing_transaction.html.

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 HCL 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 HCL 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 HCL 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 HCL 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 = SessionBeanHelper.lookupSessionBean(ServerJDBCHelperBean.class).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;
	}
}