Introduction

This document describes the Tracking Framework feature of Intershop Commerce Management.

The work of web analytics engines like WebTrends, Omniture, Google Analytics can be divided into three major parts:

• Collection of data
• Generating reports
• Presentation (e.g. in a tracking pixel) or export of report data (e.g. via WebService)

It is nearly the same for recommendation engines like Prudsys, Avail, which mostly do the same three things:

• Collecting data
• Generating reports
• Presentation (e.g. as user fitting products)

The Tracking Framework defines events that can be triggered, provides components to pipeline developers, and offers interfaces and managers for web analytics engines or recommendation engines respectively.

The pipeline developer adds Tracking Framework specific pipelets to pipelines, so that events are triggered. An event is an object that is passed to the tracking manager ( TrackingMgr) by the pipelet. The TrackingMgr is the bridge between the events and the registered handlers.

The picture above shows how the parts work together. The Fire...Event pipelets (these are Tracking Framework specific pipelets, e.g. FireUerLoginEvent), build up the event objects based on its input parameters and call the TrackingMgr with the event.

The TrackingMgr looks into its dictionary to see which TrackingEventHandler s are registered for the certain event and calls them one after another. With the help of the Component FW the event handler will be registered on the corresponding tracking service definition. The service definitions are registered on the service definition registry (See Service Definition Registryfor details).

The Events

Events can be basically any Object, though it should be considered as a non-persistent POJO. The framework is supertyping-aware. That means, if a sub-type event occurs, but a handler is registered for super-type events, it is still triggered for that event.

Example

The image above shows how the call structure is built up. The core functionality is enclosed in TrackingMgr.

Basically, we consider there is an event called B which is a sub-type of A. At the TrackingMgr, TrackingEventHandler s are registered: Handler X, Handler Y, and Handler Z.

• Handler X is registered for any event (because all Java classes derive from Object).
• Handler Y is registered for both A events and any other event.
• Handler Z is registered for B events only.

Now we consider there is a corresponding pipelet called FireBEvent. What happens if it calls the TrackingMgr with a B event?

1. First, the TrackingMgr finds Handler Z registered for B events, so it calls Handler Z with B.
2. Second, it looks up the superclass of B which is A. The TrackingMgr finds Handler Y registered for A events, so it calls Handler Y with B. Handler Y accepts B objects even if it only "knows" A objects, since B are A objects.
3. Third, it looks up the superclass of A which is Object. The TrackingMgr finds Handler X registered for any event, so it calls Handler X with B. It also finds Handler Y registered for any event, but please note: This handler has already been called with A, so it will not be called again with the B object.

It is common usage to define events in XSD. This is because it:

1. Assures no Enfinity persistence types are used and
2. Streaming those data to a remote system, maybe by transforming it, is straightforward.

Available Events

The following table displays all available events.

Available Data

This table describes all data objects for implemented tracking events.

Good Practice

Think About Event Inheritance

All Events inherit from other Tracking Events. It is possible to listen to the corresponding events or to a root event, e.g., listen to the UserLoginEvent and UserLogoutEvent Events or to the root event UserActionEvent. New Events should inherit from an applicable Business Tracking Event. So think about the correct inheritance and do not simply use the TrackingEvent.

Use Tracking Data Objects

Any event defines its own set of data that it needs for processing. For these purposes, so-called Tracking Data Objects can be used. These objects should be created if they are used multiple times (for a number of events) or if they should represent a business object relation. As they are not directly connected with Enfinity's business objects, it is suggested to implement JAXB objects. This requires some mappers that map Enfinity's business objects to those JAXB objects. These mappers are called inside the Concept - Business Tracking#Fire..Eventpipelets.

Events and Data Objects Are Only Containers

The TrackingEventHandler expects that the Events and their data are only data containers. This means that they do not have methods which determine, calculate, create, or remove something. It is suggested to use JAXB to create new Events and new Event Data Objects.

TrackingService

The TrackingService implementing ServiceDefinition is a stateless service object. It is created when loading the cartridge from the Component FW and is registered on the managed service framework.
It also manages the TrackingEventHandler.

TrackingEventHandler

The TrackingEventHandler is a stateless component that receives an event and does "something" with it. It may call any remote tracking services or perform some local tracking tasks - whatever is needed.

The "do something" functionality is encapsulated in the handleEvent method. Since a "certain something" cannot not be more precisely described, both input and output parameters are generic (The event and tracking data container are just of the type Object).

There are 2 more methods defined in the TrackingEventHandler.

• getId defines the Id of the handler
• getEventTypes lists the event types the handler understands. Usually the types listed there should not be in a superclass-subclass relation (See the paragraph about event hierarchies in this document)!

TrackingDataContainer

Introduction
The TrackingEventHandler and the TrackingService must be imagined as a stateless object. However, it should be possible to use some data from previous calls of that handler or service to enable that the pipeline is a holder of an object that is used as a tracking data container. It has no defined interface because it is completely unclear what kind of attributes and methods a tracking data container may own. So it is defined as being an Object. Each pipelet accepts a tracking data container as an input parameter and serves a tracking data container as an output parameter.

• Instantiation
  The instantiation of the tracking data container takes place in the handler or service respectively. That means, when triggering an event for the first time (in a request), the input parameter for the Fire..Pipelet will be null. The pipeline will never do anything with it, it just reads and writes it to the pipeline dictionary. A handler or service implementation may instantiate an object as needed and return it as a tracking data container.

• Lifetime
  The lifetime ends when the actual request is completely processed.

Fire..Event Pipelets

The Fire..Event pipelets are the bridge between the tracking framework and pipeline development. Placing a Fire..Event pipelet anywhere in a pipeline means to let a certain event occur at runtime.

The tasks of Fire..Event Pipelet are

1. looking up values in pipeline dictionary
2. creating the event object from the input values
3. handing over the event to the TrackingMgr
4. putting the return tracking data container to the pipeline dictionary

Since the creation of the event object from the input values is the most complex from the tasks above, it is sourced out to mappers. By now, those mappers are hard-wired. It is important to prove that the event can be built up by the mandatory input parameters, but the mapper must not fail if a value that is not mandatory is missing.

Wiring

The components described here are wired with the help of the Component FW. Adding another TrackingEventHandler means to register it on the corresponding tracking ServiceDefinition. This ServiceDefinition is registered on the service definition registry (see Service Definition Registryfor details).

Exception Handling

Usually an exception in a TrackingService or in a TrackingEventHandler should not interrupt the process flow. On the other hand, it might be necessary during development or qa tests to find exceptions very early. This is why it is configurable how the system acts on an exception: it can just log the error and return and continue as if nothing happened, and it can throw the exception so the user will get an exception page displayed.

The difference between Default configuration and Fallback is: The Default configuration is the configuration to be found in the file when setting up the system. The Fallback is used if no configuration for that key is to be found at all or if no known value can be found.