Location component interactions

The Location component uses several methods to interact with client location records. This interaction includes methods that help collect, resolve, filter, and persist client records. These methods query Points of Interest, dispatch location events, and invoke and use the Customer Checks In marketing trigger.

When a client location record is reported to the Location component, ChangeClientLocationBasePartCmdImpl calls a sequence of commands, which direct the processing of the client location report. This sequence of commands forms a command pipeline, which refines and resolves the raw information (such as latitude and longitude) in an incoming client location report. The pipeline culminates in a set of output client location reports, which are linked to particular points of interest. The pipeline might be customized by providing a subclass of ChangeClientLocationBasePartCmdImpl, which overrides the getPipelineCommandInterfaces() method. The getPipelineCommandInterfaces() method emits an ordered list of command interface names to be used in pipeline processing. The default pipeline processing is described in the following workflow:

Collecting client location records

A location source can report a client location record to the Location component by calling:

Collecting client location records (OAGIS)
OAGIS service	Action code	Expression
ChangeClientLocation	Change	/ClientLocation[1]

Alternatively, it can call:

Collecting client location records (REST)
REST service	Method
clientLocation	PUT

Filtering client location records

After ChangeClientLocationBasePartCmdImpl calls ResolveClientLocationCmd, it then calls FilterClientLocationCmd to check whether the client location record requires further processing.

Its default implementation, FilterClientLocationCmdImpl, for the GPS source type filters client location records by properties such as client type, source type, POI type, region ID, or zone ID.

The default implementation of Filter drops records that do not have a ClientType of User, and does not examine any other fields.

Resolving client location records

Its default implementation, ResolveClientLocationCmdImpl, for the GPS source type attempts to resolve the following information:

Point of Interest ID, if not specified by the location source, and related fields, for example POI type, region ID, or zone ID, from its geographic location.
Client location record ID, if not specified by the location source, if there is an existing record in the database with the specified client ID, source type and Point of Interest ID.
Expiration time, if not specified by the location source, from the DefaultExpirationTimeOffset/source_type configuration property, which specifies the source type default expiration time that is offset in milliseconds.

The following table indicates how a Point of Interest ID is resolved:

Client location
Client location	Point of Interest location	Resolved location to a Point of Interest?
A	B, within radius range. C, out of radius range.	Yes, only the Point of Interest that is represented by B. A client location record is created matching POI B.
A	D, within radius range. E, within radius range.	If accuracy is zero meters: Yes, the single Point of Interest that is closest to the client location by default. Client location records are created matching either POI D or POI E, depending on which location is closer to the client location. If accuracy is greater than zero meters: Yes, multiple Points of Interests (POI D and POI E) are resolved. A client location record is created matching both POI D and POI E. Note: This behavior can be customized to suit your business needs.
A	F, out of radius range.	No, Points of Interest are not in range. No client location records are created matching a POI.

Note: It is possible for a client location to move out of a point of interest radius as the client GPS accuracy improves.

Dispatching location events

After ChangeClientLocationBasePartCmdImpl calls ResolveClientLocationCmd, it then calls DispatchLocationEventCmd to dispatch a location event.

By default, DispatchLocationEventCmdImpl calls MarketingFacadeClient.evaluateMarketingTrigger(Map) to dispatch a location event to the Marketing component.

The default implementation considers two thresholds, one in space and one in time, in making its decision. These thresholds are defined in the wc-component.xml configuration file.

The wc-component.xml file can be found in the WC_eardir/xml/config/com.ibm.commerce.location directory. By default it contains the following threshold configurations:


<_config:configgrouping name="MarketingEngineParameters"> 
<_config:property name="TimeThresholdMilliseconds" value="60000"/> 
<_config:property name="DistanceThresholdMeters" value=""/> 
</_config:configgrouping>

As with any component customization file, it can be extended to suit your business needs.

The space threshold invokes the Marketing engine if the physical distance between consecutive ClientLocations exceeds the threshold. The time threshold invokes the Marketing engine if the time difference between publication of consecutive ClientLocations exceeds the threshold.

Note: Consecutive ClientLocations must meet either the space or the time threshold to invoke the Marketing engine. For example, this logic ensures that:

A customer check-in at a store on day 1 and the same store again on day 2 invokes the Marketing engine on both days (time threshold met)
A customer check-in at one store followed by a check-in at a different store within the time threshold invokes the Marketing engine for both stores (space threshold met).

To compute whether a customer's previous and current locations meet the thresholds, an in-memory cache is maintained of ClientLocations (one record per PersonalizationID). This behavior can be amended by extending or replacing the DispatchClientLocationEventCmd.

Querying Points of Interest

The Location component provides the OAGIS GetPointOfInterest service and its corresponding REST GET pointOfInterest service to query points of interest by parameters such as store ID, POI type, region ID, zone ID, or geographic location.

The parameters are used for the following tasks:

When you are creating a location-based marketing activity, a marketing manager is given the geographic regions (Points of Interest of type Region) and store locations (Points of Interest of type Store) that the activity can target.
When there are multiple nearby store locations, a shopper is given the nearby store locations (Points of Interest of type Store) that they can check in to.

Trigger: Customer Checks In

The Customer Checks In trigger in the Marketing tool is used to create location-based dialog activities. This trigger can be used in a dialog activity to begin or continue the activity when a shopper checks in to a Point of Interest a specified number of times within a specified time frame.

The marketing engine is notified by the Location component when you are using this trigger. The notification occurs by calling the Process Marketing Trigger Web service, through the MarketingFacadeClient method evaluateMarketingTrigger(Map parameters).

The following snippet is an example of the service call:


Map parameterMap = new HashMap();
parameterMap.put("DM_ReqCmd", "LocationEvent");
parameterMap.put("storeId", "10001");
parameterMap.put("userId", "10001");
parameterMap.put("personalizationId", "10001");
parameterMap.put("action", "Check-in");

parameterMap.put("pointOfInterestId", "10001");
parameterMap.put("regionId","CA-ON");
parameterMap.put("zoneId","Markville Mall Store");
marketingFacadeClient.evaluateMarketingTrigger(parameterMap);

Each location event includes the following name-value pairs:

Location event name-value pairs
Name	Description
DM_ReqCmd	The name of the event. The value must be `LocationEvent`.
storeId	The HCL Commerce store ID.
userId	The HCL Commerce user ID.
personalizationId	The HCL Commerce personalization ID.
action	The action that triggers the event. The value must be `Check-in`.
pointOfInterestId	The Point of interest ID.
regionId	The region ID.
zoneId	The zone ID.