Document Properties
Kbid2E3277
Last Modified23-Jun-2020
Added to KB18-Jun-2012
Public AccessEveryone
StatusOnline
Doc TypeGuidelines, Concepts & Cookbooks
Product
  • ICM 7.6
  • ICM 7.7
  • ICM 7.8
  • ICM 7.9
  • ICM 7.10

Concept - Business Tracking

1 Introduction

This document describes the Tracking Framework feature of the Enfinity platform.

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.

TrackingFrameworkBigPicture

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

2 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

TrackingFrameworkEventHierarchy

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.

2.1 Available Events

The following table displays all available events.

Event

Is subtype of

Description

Attributes

TrackingEvent

Object

The root event for any other events

-

ViewEvent

TrackingEvent

The root event for all viewing events; Note: This event exists as a concrete event object itself and is not just an abstract superclass


  • Session: for details see TrackingSession
  • PageInformation: for details see TrackingPageInformation \\\\\\\\\\\\

ProductActionEvent

TrackingEvent

The root event for all product action events


  • Session: for details see TrackingSession
  • PageInformation: for details see TrackingPageInformation
  • ProductItem: for details see TrackingProductItem \\\\\\\\\\\\

UserActionEvent

TrackingEvent

The root event for all user action events


  • Session: for details see TrackingSession
  • PageInformation: for details see TrackingPageInformation
  • User: for details see TrackingUser \\\\\\\\\\\\

ViewPageEvent

ViewEvent

An event for viewing pages


  • Order: for details see TrackingOrder \\\\\\\\\\\\

ViewBasketEvent

ViewEvent

An event for viewing the basket


  • Basket: for details see TrackingBasket \\\\\\\\\\\\

ViewProductEvent

ViewEvent

An event for viewing products


  • Product: for details see TrackingProduct \\\\\\\\\\\\

ViewCategoryEvent

ViewEvent

An event for viewing categories


  • Category: for details see TrackingCategory \\\\\\\\\\\\

BasketAddProductEvent

ProductActionEvent

An event for adding a product to the cart

-

BasketRemoveProductEvent

ProductActionEvent

An event for removing a product from the cart

-

UserLoginEvent

UserActionEvent

An event for user is now logged in

-

UserLogoutEvent

UserActionEvent

An event for user is now logged out

-

OrderPlacedEvent

TrackingEvent

An event for viewing order information


  • Session: for details see TrackingSession
  • Order: for details see TrackingOrder \\\\\\\\\\\\

2.2 Available Data

This table describes all data objects for implemented tracking events.

Name

Is subtype of

Description

Attributes

TrackingBasket

Object

A container object for basket-related information


  • id: basket identifier
  • productItems: product at basket; for details see TrackingProductItem \\\\\\\\\\\\

TrackingCategory

Object

A container object for category-related information


  • id: identifier of category
  • name: name of category in the language of the current request
  • parent: parent category (get levels of category); for details see TrackingCategory
  • subCategories: collection of sub-categories (sorted by name); for details see TrackingCategory \\\\\\\\\\\\

TrackingMoney

Object

A container object for money-related information


  • value: a decimal value of the money object
  • currency: The ISO 4217 currency mnemonic (such as 'USD', 'EUR') of the currency the money value relates to. \\\\\\\\\\\\

TrackingOrder

Object

A container object for order-related information


  • orderNo: order document number
  • creationDate: order creation date
  • productItems: product at order; for details see TrackingProductItem \\\\\\\\\\\\

TrackingPageInformation

Object

A container object for page-related information


  • pageName: name of page - e.g. name of product, name of category, name of page
  • pageType: symbolic name of page, e.g. "basket", "product", "category", "account", "checkout", "general"

TrackingProduct

Object

A container object for product-related information


  • id: uuid of product
  • repositoryId: ID of repository
  • sku: identifier of product
  • name: display name of product in the language of the current request
  • description: short description of product in the language of the current request
  • productType: technical classification of product, e.g. "standard", "master", "variation", "bundle", "customizable", "configurable"
  • primaryCategory: default category; for details see TrackingCategory
  • master: contains reference to master product if the product is a variation else null; for details see TrackingProduct
  • price: price of item; for details see TrackingMoney
  • manufacturerName: manufacturer name

TrackingProductItem

Object

A container object for product-item-related information


  • product: product at order; for details see TrackingProduct
  • quantity: amount of products at container
  • price: price of item; for details see TrackingMoney \\\\\\\\\\\\

TrackingSearch

Object

A container object for search-related information


  • term: original search term
  • pageSize: number of products on search result page
  • currentPage: current page \\\\\\\\\\\\

TrackingSearchResult

TrackingSearch

A container object for search result item related information


  • position: the absolute position of the product in the search result e.g. product on second page pagesize=10 would be 11
  • similarity: the similarity the item has for the query term \\\\\\\\\\\\

TrackingSearchFeedback

TrackingSearch

A container object for search-result-item-related information, e.g. a feedback form to let customers comment upon the search result. There is no such functionality yet in the demo store.


  • positive: if user is positive about the searchresult
  • message: a user-entered message \\\\\\\\\\\\

TrackingSession

Object

A container object for current session-related information


  • id: identifier of session
  • user: current user of session; for details see TrackingUser \\\\\\\\\\\\

TrackingUser

Object

A container object for current session-related information


  • id: identifier of user \\\\\\\\\\\\

2.3 Good Practice

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

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

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

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

4 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)!

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

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

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

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

Configuration file

%IS_HOME%/share/system/config/cluster/appserver.properties

Property

intershop.tracking.OnError

Possible values

  • LOG
  • EXCEPTION

Default configuration

EXCEPTION

Fallback

LOG

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.

Disclaimer

The information provided in the Knowledge Base may not be applicable to all systems and situations. Intershop Communications will not be liable to any party for any direct or indirect damages resulting from the use of the Customer Support section of the Intershop Corporate Web site, including, without limitation, any lost profits, business interruption, loss of programs or other data on your information handling system.

Customer Support
Knowledge Base
Product Resources
Support Tickets