| Download Docs | Site Map | Glossary | |
|
|
|||
| bea.com | products | dev2dev | support | askBEA |
|
|
|
|||||||
 |
| e-docs > WebLogic Platform > WebLogic Portal > Development Guide > Event and Behavior Tracking |
|
Development Guide
|
Event and Behavior Tracking
The Event system provides you with the ability to identify the interactions that visitors have with your portal or Web site.
Customer interactions One of the primary uses of events is in customer interactions such as promotions or campaigns. A simple example of using events in a campaign is triggering the display of an ad for a related product when a customer places an item in a shopping cart.
Behavior Tracking Another primary use of events is to track visitor behavior by recording events. Recording events is more than just navigation logging, which tells you only what pages were visited. Behavior Tracking allows you to know what the visitor saw and responded to, or equally important, ignored on a page. Recording events in a database allows leading e-analytics and e-marketing systems to use event data for data mining. Analyzing event information helps you create or enhance the rules that customize the content of your site to each visitor and evaluate the effectiveness of your promotional campaigns
Custom events The Event system allows you to create your own events. For example, you could create an event that records who visits each portlet and how often each portlet is accessed. When you create a custom event, the event can either be recorded to a database using the WebLogic Portal persistence mechanism or not be recorded using this mechanism. Events that are persisted are called Behavior Tracking events. If your custom event will be not persisted, follow the instructions in Writing the Custom Event Class. If you are creating a custom Behavior Tracking event, follow the instructions in Writing a Behavior Tracking Event Class.
The subject matter in this section is primarily intended for J2EE experts. It includes information about the following subjects:
How Events Work in Campaigns
An event is generated by a visitor action, such as viewing a product. The Event service notifies all event listeners that it has detected the event. The event listener for the Campaign service activates a campaign scenario. Using a set of rules that match users with content, the campaign initiates an action. The available actions are listed below:
Note: For more information about campaigns, see the E-Business Control Center online help.
How the Event Service Works
Understanding how the Event service works helps you use events and provides information you need to generate events and design a custom event.
About the Event service The Event service is an extensible, general purpose, event construction and propagation system. As shown in Figure 15-1, an event is generated by a trigger, such as a JSP tag, which creates the event object, locates the Event service bean, and passes the event object to the Event service. The Event service works with plug-in listeners that disseminate events to listeners interested in receiving the events. At creation time, each event listener returns the list of event types that it wants to receive. When the Event service receives an event, it checks the type of the event and sends the event to all listeners that are subscribed to receive that event's type.
Listener types The Event service has two sets of listeners: those that respond to events synchronously and those that respond to events asynchronously. The synchronous listeners use the thread of execution that created and transmitted the event to perform actions in response to that event. Behavior Tracking listeners use only the synchronous listeners. The asynchronous listeners receive the event from the thread where it was created and some time later, handles the event in a different thread of execution. The asynchronous service exists so that long-running event handlers can execute without delaying the application from a Web site visitor's perspective.
Whether a particular plug-in listener is installed on the synchronous or the asynchronous side of the Event service is based on the requirements of the application. Configuration of the Event service is done using the WebLogic Server Administration Console.
Figure 15-1 Event Mechanism
The first method returns a list of event types that the listener is interested in receiving from the Event service. For example, if a listener is designed to receive events of type Foo, the listener returns Foo as an item in the array returned from invoking getTypes() on the listener. The second method is invoked when an event is passed to the listener. A listener has no knowledge of whether it is synchronous or asynchronous.
If you wish to create a listener interested in only campaign events, you would add the listener's fully-qualified classname in the WebLogic Server Administration Console. The listener would implement the EventListener interface and return the following event types:
{"ClickCampaignEvent","DisplayCampaignEvent","CampaignUserActivityEvent" }when its getTypes() method is invoked.
After the listener is installed, events of one of these three types arrive through the listener's handleEvent( Event theEvent ) interface.
The Asynchronous Delivery graphic in Figure 15-1 indicates that the asynchronous event handler receives events transmitted asynchronously from the synchronous side of the Event service. It then dispatches events to the pluggable asynchronous listeners based on the event types each listener is subscribed to receive.
How Event Sequences Work
Figure 15-2 and Figure 15-3 provide a sample of the generation of events. These figures are intended to give you a sense of the order in which events fire, not a comprehensive examination of event sequencing. The intent is to show you how events provide insight into the visitor life cycle and how and when you can use events in your application.
Figure 15-2 Event Sequence Sample—Part 1
Figure 15-3 Event Sequence Sample—Part 2
How to Use Standard Events
This section provides general information about how to use the standard events provided with WebLogic Portal. For specific information about each event, see Event Descriptions. Appendix A contains a description of each kind of event, what generates the event, the class where event generation occurs, an example of usage, and the type of data within each event object.
All WebLogic Portal standard events contain the following basic information:
WebLogic Portal events are organized into categories. The following list presents each type of event category along with a brief description of what actions generates the event:
Servlet Lifecycle Events and Servlet Filter Events
These events are defined as part of the Servlet 2.3 API lifecycle events:
They are listeners on the session Created() and session Destroyed() events, which are generated by the servlets defined in the web.xml file. One web.xml file exists for each application. For example, in wlcsApp E-Commerce Application, this file is located at:
<BEA_HOME>\weblogic700\portal\applications\wlcsApp\wlcs\WEB-INF
The following events are generated by JSP tags and filtered by the Servlet 2.3 <filter> element:
For each Web page displayed, the Web Application servlet checks for the presence of a click event in the HttpServletRequest. Each page click is then filtered by a Web Application servlet as defined by the Servlet 2.3 <filter> element. The click events are generated automatically when the <filter> element is called on each invocation of the servlet. The ClickThroughFilter determines which type of event is generated by checking the event type in the HttpServletRequest. The valid types are defined at the following locations:
Generating Login and Creation Events
This section describes different methods you can use to generate login and user registration events.
SessionLoginEvent You can generate the SessionLoginEvent in either of the following ways:
UserRegistrationEvent Use the com.bea.p13n.tracking.TrackingEventHelper.dispatchUserRegistrationEvent() method to generate the UserRegistrationEvent. You should generate this event after the SessionLoginEvent (which should occur during user creation). You can use either an Input Processor or in a JSP.
Webflow If you are using the Portal Webflow framework, the SessionLoginEvent and the UserRegistrationEvent are generated automatically from the com.bea.portal.appflow.processor.security.PostLoginProcessor in the security Webflow as needed.
Adding or Customizing Event Generators
Standard events are generated at important points in an e-commerce site. The components that enable events include Java APIs, JSP tags, JSP scriptlets, Webflow input processors, Pipeline components, content selectors, and classification advislets. You can add or customize generators for each of the following events:
Each event is generated by JSP tags. You can use the JSP tags that initiate these events to specify which products and what content generate these events. For example, in the wlcsApp E-Commerce Application, the JSP tag for the DisplayProductEvent is located in the details.jsp.
The tag shown in Listing 15-1 generates an event for any product displayed on a catalog detail page. If you want to generate an event for one particular product, you can write a scriptlet that keys off the SKU for that product.
Listing 15-1 JSP Tag
<%-- once the product is displayed, fire off a displayProductEvent --%>
<productTracking:displayProductEvent documentId="<%= item.getName() %>"
documentType="<%= DisplayProductEvent.ITEM_BROWSE %>"
sku="<%= item.getKey().getIdentifier() %>" />
When you add a JSP tag for an event, you should include a reference to the tag library descriptor, as shown below:
<%@ taglib uri="productTracking.tld" prefix="productTracking" %>
The details.jsp is located in the following directory:
<BEA_HOME>\weblogic700\portal\applications\wlcsApp\wlcs\commerce\catalog
Creating Custom Events
This section provides the information necessary to write a custom event. You can create a custom event for anything you wish to track. If you want your event to be recorded using the WebLogic Portal persistence mechanism, create a Behavior Tracking event, as described in Writing a Behavior Tracking Event Class.
Idea for a custom event You could create an event that would tell you which pages are displayed for each visitor. You could then use the information to determine how many pages are viewed on average per session and which pages are the most popular. Additionally, marketing professionals could use this event when developing promotional campaigns that are based on the display of particular pages.
To demonstrate how to write a custom event, a simple example is provided. Each section references and expands the example.
The creation of a custom event is a multiple-step process. The following list provides an overview of the process and references the information not covered in this topic:
Writing the Custom Event Class
To create a custom event, take the following steps:
All custom events must subclass the com.bea.p13n.events.Event class. This base class handles setting and retrieving an event's timestamp and type and provided access to the custom event's attributes. Two Event class methods set and retrieve attributes:
setAttribute( String theKey, Serializable theValue )
getAttribute( String theKey )
These methods can be called from the custom event's constructor to set attributes specific to the new event. Keep in mind that all objects set as values in the Event object must be Java serializable.
The getTimeStamp() method returns the date of the event's creation in milliseconds. The type of an event is accessed using the Event class's getType() method. The timestamp and type of an Event object instance can be set only at creation time in the Event constructor. If not specified, the event is timestamped automatically when it is created. The application attribute is set automatically, either from the application in which the event was created or from the Event service EJB (Enterprise JavaBean) application.
Example To illustrate the process of creating a custom event, a simple example is presented here, called TestEvent. The example is a basic demonstration of how to create an event subclass. An actual custom event would probably be more elaborate.
/** Event Type */
public static final String TYPE = "TestEvent";
/**
* Event attribute key name for the first user defined property
* Attribute value is a String
*/
public static final String DESCRIPTION = "description";
/**
* Recall that all attribute values must be serializable
* Event attribute key name for the second user defined
* property
* Attribute value is an Integer
*/
public static final String ZIP_CODE = "Zip Code";
Finally, a constructor brings the event type and the process of setting attributes together to create an event object. The constructor looks like:
/**
* Create a new TestEvent
*
*
* @param desc The description of this event
* @param zip The Zip Code
*/
public TestEvent( String desc, Integer zip )
{
/* calls the Event class constructor with this event's
type */
super( TYPE );
if( desc != null )
setAttribute( DESCRIPTION, desc );
if( zip != null )
setAttribute( ZIP_CODE, zip );
}
All the parts put together The entire custom event class is shown in Listing 15-2.
Listing 15-2 TestEvent Class
/* Start TestEvent class */
public class TestEvent
extends com.bea.p13n.events.Event
{
/** Event Type */
public static final String TYPE = "TestEvent";
/**
* Event attribute key name for the first user defined property
* Attribute value is a String
*/
public static final String DESCRIPTION = "description";
/**
* Event attribute key name for the second user defined property
* Attribute value is an Integer
*/
public static final String ZIP_CODE = "Zip Code";
/**
* Crate a new TestEvent
*
*
* @param desc The description of this event
* @param zip The Zip Code
*/
public TestEvent( String desc, Integer zip )
{
/* calls the Event class constructor with this event's type */
super( TYPE );
if( descriptionValue != null )
setAttribute( DESCRIPTION, desc );
if( ZipCodeValue != null )
setAttribute( ZIP_CODE, zip );
}
}
/* End TestEvent class */
About the example The example in Listing 15-2 shows you how to use the fundamental aspects of the Event base class and the Event service. An actual custom event constructor would probably be more complex. For example, it might check for default values or disallow null attributes. Additionally, the custom-event object might have more methods or member data.
Note: In order for a custom event to be used by a campaign, it must contain the following objects as attributes:
Saving the file You can save the file anywhere you like as long as it is in the enterprise application classpath used by WebLogic Server.
Writing the Custom Event Listener
In order to listen for an event, you must define an event listener. All event listeners must implement the com.bea.p13n.events.EventListener interface and have a no arguments (default) constructor. This interface specifies two methods that are fundamental to transmitting events of a given type to interested listeners:
public String[] getTypes()
public void handleEvent( Event ev )
The first method returns the types, in a string array, that the listener is interested in receiving. The Event service dispatches events of a given type to listeners that return the event's type in the types array. When the Event service has determined that a given listener has registered to receive the type of the current event, an event of that type is dispatched to the listener using the handleEvent( Event ev ) call.
Implement both event listener methods When writing a custom event listener, both methods must be implemented from the EventListener interface. Continuing with the TestEvent example, the TestEventListener listens for instances of TestEvent that are sent through the Event service. This can be specified as follows:
/** The types this listener is interested in */
private String[] eventTypes = {"TestEvent"};
/**
The method invoked by the event service to determine the
types to propagate to this listener.
*/
public String[] getTypes()
{
return eventTypes;
}
To handle the event, the handleEvent( Event evt ) method is implemented as follows:
/**
* Handle events that are sent from the event service
*/
public void handleEvent( Event ev )
{
System.out.println("TestListener::handleEvent " +
" -> received an event" +
" of type: " + ev.getType() );
/* Do the work here */
}
Putting all of these pieces together with a constructor, Listing 15-3 shows a simple event listener that registers to receive TestEvent objects.
Listing 15-3 Event Listener
import com.bea.p13n.events.EventListener;
import com.bea.p13n.events.Event;
/**
* TestListener to demonstrate the ease with which listeners can be plugged
* into the behavior tracking system.
*
* This class should be added to the property eventService.listeners
* in order to receive events. The fully qualified classname must be added
* to this property; don't forget to add the ",\" at the end of the previous
* line or the properties parser will not find the new classname.
*
* The types of events that are heard are listed in the eventTypes
* String array. Add and remove strings of that type as necessary.
*
* @author Copyright (c) 2001 by BEA Systems, Inc. All Rights Reserved.
*/
public class TestListener
implements EventListener
{
private String[] eventTypes = {"TestEvent"};
public TestListener()
{
}
public String[] getTypes()
{
return eventTypes;
}
public void handleEvent( Event ev )
{
System.out.println("TestListener::handleEvent -> received an event" +
" of type: " + ev.getType() );
return;
}
}
Event listeners should be generic As with writing a simple event, writing a simple EventListener is also straightforward. Any event listener's internals should be generic; the same TestEventListener instance may not handle all TestEvent objects. Therefore TestEventListener should be entirely stateless and should operate on data that is contained in the event object or stored externally in a database.
Note: Multiple instances of any listener may execute concurrently.
Installing the Listener Class in the Event Service
Notes: This section provides information on how to add a listener class in the Sample Portal. For your application, you would use similar steps.
If the Event service does not exist as a service for your application, use WebLogic Server Administration Console to add it.
To enable Behavior Tracking, you must add Behavior Tracking as a synchronous listener to the Event service.
Add a listener To add a synchronous or asynchronous listener, take the following steps:
Note: Behavior Tracking listeners can only be implemented as synchronous listeners.
Figure 15-4 WebLogic Server Administration Console—Event Service
Writing a Behavior Tracking Event Class
A Behavior Tracking event is a special type of event that tracks a visitor's interactions with a Web site. E-analysis systems use the data gathered from Behavior Tracking events to evaluate visitor behavior. The evaluation is primarily used for campaign development and optimizing visitor experience on a Web site.
Example A Behavior Tracking event and its listeners are created in much the same way as the TestEvent class and TestEventListener examples. A simple example is also presented here. The example tracking event is called TestTrackingEvent. All Behavior Tracking events persisted (recorded) to a database for use with BEA Behavior Tracking are handled by the com.bea.p13n.tracking.listeners.BehaviorTrackingListener. The BehaviorTrackingListener extends the com.bea.p13n.events.EventListener class.
Redeploy After the BehaviorTrackingListener is defined as a listener on the Event service, you need to redeploy the application before it can receive and persist Behavior Tracking events.
About the buffer This listener receives events from the Event service and adds them to a buffer that is intermittently persisted to the Event tables in the database. The frequency of sweeping of events from the buffer is controlled by the following properties on the Behavior Tracking service.
Optimizing Tune these properties to optimize performance. A buffer sweep should be performed often enough that writing to the database is not too time consuming but not so frequent that the operation is wasteful.
Configuring Events Buffer Sweeping
Notes: This section provides information on configuring buffer sweeping in the Sample Portal. For your application, you would use similar steps.
If the Event service does not exist as a service for your application, use WebLogic Server Administration Console to add it.
To configure the sweeping of the events buffer, take the following steps:
Figure 15-5 WebLogic Server Administration Console—Behavior Tracking
Facilitating OffLine Processing
Behavior Tracking events are designed to be persisted to a table in the database, called the EVENT table. Part of the process of recording data from Behavior Tracking events is creating an XML representation of the data, which is stored in the xml_definition column of the EVENT table. If you are planning to use the BEA Behavior Tracking event persistence mechanism, you must persist events in this location. Therefore, to persist events in the provided EVENT table, your custom event must conform to the descriptions in this section so that it is created and persisted properly.
XML-XSD schema To formally specify the data contained in a Behavior Tracking event, you need to develop an XML-XSD schema for the new event. While XSDs are not used internally to verify the creation of XML, the XML that is created represents the event's data in the database. If the event class is properly developed and used, it will conform to the XML-XSD schema. With an XSD document, development of the constructor and attribute keys for a Behavior Tracking event follows easily. The specific data elements for each standard event are shown in the XML_DEFINITION Data Elements table in the Administration Guide at http://download.oracle.com/docs/cd/E13218_01/wlp/docs70/admin/sysadmin.htm#1195110.
Association between files To correctly turn a Behavior Tracking event into an XML representation, the Behavior Tracking event must have several pieces of member data that fully describe an XML instance document for the schema associated with the event type. This data describes the namespace and XSD file associated with the event. For example, Listing 15-4 and Listing 15-5 show the association between the following files:
com.bea.campaign.tracking.events.ClickCampaignEvent and
/lib/schema/tracking-click-campaign-1_0_1.xsd in <BEA_HOME>\weblogic700\portal\\lib\campaign\ejb\campaign.jar.
For more examples, look at the existing XSD files.
Listing 15-4 ClickCampaignEvent.java
/**
Event for tracking click of campaign
*/
public class ClickCampaignEvent
extends ClickEvent
{
/** The event type */
public static final String TYPE = "ClickCampaignEvent";
/**
The XML namespace for this event
*/
private static final String XML_NAMESPACE =
"http://www.bea.com/servers/commerce/xsd/tracking/click-campaign/1.01";
/**
The XSD file containing the schema for this event
*/
private static final String XSD_FILE = "tracking-click-campaign-1_0_1.xsd";
/**
* Event attribute key name for the campaign id
* Attribute value is a String
*/
public static final String CAMPAIGN_ID = "campaign-id";
/**
* Event attribute key name for the scenario id
* Attribute value is a String
*/
public static final String SCENARIO_ID = "scenario-id";
/**
* Event attribute key name for storefront (aka application-name)
* Attribute value is a String
*/
public static final String APPLICATION_NAME = "application-name";
/**
* Event attribute key name for item category id
* Attribute value is a String
*/
public static final String PLACEHOLDER_ID = "placeholder-id";
/**
Suggestions for entry into the documentType data passed to the constructor
Attribute value is a String
*/
public static final String BANNER_AD_PROMOTION = "bannerAdPromotion";
/**
These are the keys and their order for elements that
will be present in the XML representing this object
*/
private static final String localSchemaKeys[] =
{
APPLICATION, SESSION_ID, USER_ID, DOCUMENT_TYPE, DOCUMENT_ID,
CAMPAIGN_ID, SCENARIO_ID, APPLICATION_NAME, PLACEHOLDER_ID
};
/**
* Create a new ClickCampaignEvent.
*
* @param theSessionId from HttpSession.getId()
* @param theUserId from HttpServletRequest.getRemoteUser() or
* equivalent (null if unknown)
* @param theRequest the http servlet request object
* @param aDocumentType Document Type for the clicked content (optionally
* null)
* @param aDocumentId Document ID for the clicked content (optionally null)
* @param aCampaignId campaign id for the campaign from which the item was
* clicked
* @param aScenarioId scenario id for the scenario (within the campaign)
* for which the item was clicked
* @param aApplicationName application name (aka storefront) (optionally
* null)
* @param aPlaceholderId a placeholder id
*/
public ClickCampaignEvent( String theSessionId,
String theUserId,
HttpServletRequest theRequest,
String aDocumentType,
String aDocumentId,
String aCampaignId,
String aScenarioId,
String aApplicationName,
String aPlaceholderId )
{
super( TYPE,
theSessionId,
theUserId,
XML_NAMESPACE,
XSD_FILE,
localSchemaKeys,
theRequest,
aDocumentType,
aDocumentId);
if( aCampaignId != null ) setAttribute( CAMPAIGN_ID, aCampaignId );
if( aScenarioId != null ) setAttribute( SCENARIO_ID, aScenarioId );
if( aApplicationName != null ) setAttribute( APPLICATION_NAME,
aApplicationName );
if( aPlaceholderId != null ) setAttribute( PLACEHOLDER_ID,
aPlaceholderId );
}
}
Event and XSD cross-referenced Notice the cross-reference between ClickCampaignEvent and the XSD schema. This association allows the Behavior Tracking data to be properly recorded in the database.
Listing 15-5 Corresponding XSD Schema
<xsd:schema
targetNamespace="http://www.bea.com/servers/commerce/xsd/tracking/click-campaign/1.0.1"
xmlns="http://www.bea.com/servers/commerce/xsd/tracking/click-campaign/1.0.1"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.w3.org/2001/XMLSchema
http://www.w3.org/2001/XMLSchema.xsd"
elementFormDefault="qualified"
attributeFormDefault="unqualified">
<xsd:element name="ClickCampaignEvent">
<xsd:complexType>
<xsd:sequence>
<xsd:element ref="application"/>
<xsd:element ref="event-date"/>
<xsd:element ref="event-type"/>
<xsd:element ref="session-id"/>
<xsd:element ref="user-id" minOccurs="0"/>
<xsd:element ref="document-type" minOccurs="0"/>
<xsd:element ref="document-id" minOccurs="0"/>
<xsd:element ref="campaign-id"/>
<xsd:element ref="scenario-id"/>
<xsd:element ref="application-name" minOccurs="0"/>
<xsd:element ref="placeholder-id" minOccurs="0"/>
</xsd:sequence>
<!-- types = banner-ad-promotion -->
</xsd:complexType>
</xsd:element>
<xsd:element name="application" type="xsd:string"/>
<xsd:element name="event-date" type="xsd:string"/>
<xsd:element name="event-type" type="xsd:string"/>
<xsd:element name="session-id" type="xsd:string"/>
<xsd:element name="user-id" type="xsd:string"/>
<xsd:element name="document-type" type="xsd:string"/>
<!-- types = banner-ad-promotion -->
<xsd:element name="document-id" type="xsd:string"/>
<xsd:element name="campaign-id" type="xsd:string"/>
<xsd:element name="scenario-id" type="xsd:string"/>
<xsd:element name="application-name" type="xsd:string"/>
<xsd:element name="placeholder-id" type="xsd:string"/>
</xsd:schema>
List the keys The source code for your Behavior Tracking event should also list the keys and their order for creating an XML instance document from an event object. For an example, see Listing 15-4. The structure of an XSD document and details on XML namespaces can be found at http://www.w3.org/XML/Schema. Several XSD schemas for BEA Behavior Tracking events can be found in /lib/schema at the following location:
<BEA_HOME>\weblogic700\portal\lib\p13n\ejb\events.jar
Specify namespace and schema The namespace and schema are specified as:
/**
The XML namespace for this event
*/
private static final String XML_NAMESPACE=
"http://<your URI>/testtracking";
/**
The XSD file containing the schema for this event
*/
private static final String XSD_FILE="TestTrackingEvent.xsd";
Note: These values are used when creating an instance document to populate the fields.
The schemaKeys are a list of strings which are keys to the event class's getAttribute and setAttribute methods. These keys are used to extract the data that populate elements in the XML instance document which represent the Behavior Tracking event. The keys should be listed in an array that consists of string-typed objects. Their order specifies the order in which they appear in the XML instance document. In the XSD files that the Behavior Tracking system generates, the order of the elements is important; an XML file will not validate with an XSD file if elements are out of order. Elements can be omitted by using the XML numOccurs keyword and setting the value to zero. For examples of how this is done, see the XSD schemas for BEA Behavior Tracking events in /lib/schema, at the following location:
<BEA_HOME>\weblogic700\portal\\lib\p13n\ejb\events.jar
Structuring the array An example array for the Behavior Tracking version of the TestEvent described above might appear as:
/**
These are the keys and their order for elements that
will be present in the XML representing this object.
*/
private static final String localSchemaKeys[] =
{
SESSION_ID, USER_ID, USER_PROPERTY_ONE_KEY,
USER_PROPERTY_TWO_KEY
};
Data elements The SESSION_ID and the USER_ID are data elements in the localSchemaKeys array that are useful in implementing a tracking event. The SESSION_ID is the WebLogic Server session ID that is created for every session object. (For more information, see the WebLogic Server documentation at http://download.oracle.com/docs/cd/E13222_01/wls/docs70/index.html.) The USER_ID field (which may be null) is the username of the Web site visitor associated with the session from which the event was generated. For some events, a user may not be associated with an event; as previously mentioned, the numOccurs for the USER_ID field in an XSD file should be zero. To persist events in the EVENT table, the SESSION_ID must be non-null.
Other attributes All Behavior Tracking events must extend the com.bea.p13n.tracking.events.TrackingEvent class. This class defines three keys that are useful for setting attributes for all tracking events, as follows:
These keys are used in setAttribute calls made in the TrackingEvent constructor when setting the SESSION_ID, USER_ID, and REQUEST (an HttPServletRequest object), respectively. They should also be used to retrieve values associated with each key when invoking Event.getAttribute (String Key) on event objects that extend TrackingEvent.
Writing a TrackingEvent Base Class Constructor
The TrackingEvent base class has a constructor that is more complicated than the Event class's constructor. The Event constructor is invoked by the super( String eventType )call in the TrackingEvent constructor. The TrackingEvent constructors are shown in Listing 15-6 and Listing 15-7.
Listing 15-6 Tracking Event Constructor—Example 1
/**
* Create a new TrackingEvent.
*
* @param theEventType the event's type
* @param theSessionId from HttpSession.getId()
* @param theUserId from HttpServletRequest.getRemoteUser() or equivalent
* (null if unknown)
* @param theXMLNamespace the namespace for an XML representation of this event
* type
* @param theXSDFile the file that contains the schema which specifies and
* enforces typing on the data in the XML file
* @param theSchemaKeys the list of keys (in their order in the XSD schema)
* representing the data to be persisted in this event's XML
*/
public TrackingEvent( String theEventType,
String theSessionId,
String theUserId,
String theXMLNamespace,
String theXSDFile,
String[] theSchemaKeys )
The TrackingEvent constructor shown in Listing 15-7 takes an HttpServletRequest object.
Listing 15-7 Tracking Event Constructor—Example 2
/**
* Create a new TrackingEvent.
*
* @param theEventType the event's type
* @param theSessionId from HttpSession.getId()
* @param theUserId from HttpServletRequest.getRemoteUser() or equivalent
* (null if unknown)
* @param theXMLNamespace the namespace for an XML representation of this event
* type
* @param theXSDFile the file that contains the schema which specifies and
* enforces typing on the data in the XML file
* @param theSchemaKeys the list of keys (in their order in the XSD schema)
* representing the data to be persisted in this event's XML
* @param theRequest the http servlet request object
*/
public TrackingEvent( String theEventType,
String theSessionId,
String theUserId,
String theXMLNamespace,
String theXSDFile,
String[] theSchemaKeys,
HttpServletRequest theRequest )
About the constructors In the first constructor, shown in Listing 15-6, the only data that can be null is theUerId; all other data is required so that the tracking event is correctly persisted to the EVENT table. In the second constructor, shown in Listing 15-7, the HttpServletRequest object can be passed in from generating locations where the HttpServletRequest object is available. This object provides the data needed to fire rules against event instances.
Note: In order to fire rules on a custom Behavior Tracking event, the HttpServletRequest and the USER_ID must be non-null. Generally, a non-null USER_ID means that a visitor is logged into a Web site. Rules cannot be fired on an event with a null user.
The TestTrackingEvent constructor is shown in Listing 15-8.
Listing 15-8 TestTrackingEvent Constructor
/**
* Create a new TestTrackingEvent
*
* @param theSessionId from HttpSession.getId()
* @param theUserId from HttpServletRequest.getRemoteUser() or equivalent
* (null if unknown)
* @param userPropertyOne some user defined property typed as a String
* @param userPropertyTwo another user defined property typed as a Double
*/
public TestTrackingEvent( String theSessionId,
String theUserId,
String userPropertyOneValue,
Double userPropertyTwoValue )
{
super( TYPE, theSessionId, theUserId, XML_NAMESPACE, XSD_FILE,
localSchemaKeys );
if( userPropertyOneValue != null )
setAttribute( USER_PROPERTY_ONE_KEY, userPropertyOneValue );
if( userPropertyTwoValue != null )
setAttribute( USER_PROPERTY_TWO_KEY, userPropertyTwoValue );
}
This constructor calls the TrackingEvent constructor to populate the required values, then sets the attributes necessary for this particular Behavior Tracking event type.
The entire TestTrackingEvent is shown in Listing 15-9.
Listing 15-9 TestTracking Event
import com.bea.p13n.tracking.events.TrackingEvent;
/**
* Test, user-defined behavior tracking event.
*
* This event can be persisted to the database.
*
*/
public class TestTrackingEvent
extends TrackingEvent
{
/** Event type */
public static final String TYPE = "TestTrackingEvent";
/**
The XML namespace for this event
*/
private static final String XML_NAMESPACE="http://<your URI>/testtracking";
/**
The XSD file containing the schema for this event
*/
private static final String XSD_FILE="TestTrackingEvent.xsd";
/**
* Event attribute key name for the first user defined property
* Attribute value is a String
*/
public static final String USER_PROPERTY_ONE_KEY = "userPropertyOne";
/**
* Event attribute key name for the second user defined property
* Attribute value is a Double
*/
public static final String USER_PROPERTY_TWO_KEY = "userPropertyTwo";
/**
These are the keys and their order for elements that
will be present in the XML representing ths object.
*/
private static final String localSchemaKeys[] =
{
SESSION_ID, USER_ID, USER_PROPERTY_ONE_KEY, USER_PROPERTY_TWO_KEY
};
/**
* Create a new TestTrackingEvent
*
* @param theSessionId from HttpSession.getId()
* @param theUserId from HttpServletRequest.getRemoteUser() or equivalent
* (null if unknown)
* @param userPropertyOne some user defined property typed as a String
* @param userPropertyTwo another user defined property typed as a Double
*/
public TestTrackingEvent( String theSessionId,
String theUserId,
String userPropertyOneValue,
Double userPropertyTwoValue )
{
super( TYPE, theSessionId, theUserId, XML_NAMESPACE, XSD_FILE,
localSchemaKeys );
if( userPropertyOneValue != null )
setAttribute( USER_PROPERTY_ONE_KEY, userPropertyOneValue );
if( userPropertyTwoValue != null )
setAttribute( USER_PROPERTY_TWO_KEY, userPropertyTwoValue );
}
}
The TestTrackingEvent, shown in Listing 15-9, correctly sets its own attributes and sets the attributes in its instantiation of TrackingEvent. This enables correct population of the XML instance document at the time of its creation. Recall that the XML instance document represents the TestTrackingEvent in the database's EVENT table.
Persisting to database If you want the custom Behavior Tracking event type to be persisted in the database, the event must be added to the behaviorTracking.persistToDatabase property in the application-config.xml file. If you are not persisting the event, you do not need to add the event type to this property.
How to Enable Behavior Tracking
Note: If the Event service does not exist as a service for your application, use WebLogic Server Administration Console to add it.
The following steps describe how to enable Behavior Tracking as a service for the Sample Portal. For your application, you would use similar steps:
Figure 15-6 WebLogic Server Administration Console—Behavior Tracking
Converting Behavior Tracking Events to XML
When persisting Behavior Tracking events to the EVENT table, the bulk of the data must be converted to XML. The XML document should conform to an XML XSD schema that you create which specifies the order of the XML elements in the XML instance document. Additionally, the schema must include the types of elements and their cardinalities. The process of creating XML from an event object is handled by a helper class that utilizes variables and constants in a Behavior Tracking event's class file. All schema documents use the namespace: http://www.w3.org/2000/10/XMLSchema and all instances of Behavior Tracking schemas use the namespace: http://www.w3.org/2000/10/XMLSchema-instance. The XML created in Listing 15-10 will conform to the XSD schema.
Listing 15-10 XSD Document Example
<xsd:schema
targetNamespace="http://www.bea.com/servers/commerce/xsd/tracking/buy/1.0.1"
xmlns="http://www.bea.com/servers/commerce/xsd/tracking/buy/1.0.1"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.w3.org/2001/XMLSchema
http://www.w3.org/2001/XMLSchema.xsd"
elementFormDefault="qualified"
attributeFormDefault="unqualified">
<xsd:element name="BuyEvent">
<xsd:complexType>
<xsd:sequence>
<xsd:element ref="application"/>
<xsd:element ref="event-date"/>
<xsd:element ref="event-type"/>
<xsd:element ref="session-id"/>
<xsd:element ref="user-id" minOccurs="0"/>
<xsd:element ref="sku"/>
<xsd:element ref="quantity"/>
<xsd:element ref="unit-price"/>
<xsd:element ref="currency" minOccurs="0"/>
<xsd:element ref="application-name" minOccurs="0"/>
<xsd:element ref="order-line-id"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="application" type="xsd:string"/>
<xsd:element name="event-date" type="xsd:string"/>
<xsd:element name="event-type" type="xsd:string"/>
<xsd:element name="session-id" type="xsd:string"/>
<xsd:element name="user-id" type="xsd:string"/>
<xsd:element name="sku" type="xsd:string"/>
<xsd:element name="quantity" type="xsd:double"/>
<xsd:element name="unit-price" type="xsd:double"/>
<xsd:element name="currency" type="xsd:string"/>
<xsd:element name="application-name" type="xsd:string"/>
<xsd:element name="order-line-id" type="xsd:long"/>
</xsd:schema>
Constructing the XML Creation of an event's representation in XML takes place generically relative to the event's type. Consequently, to create an accurate XML instance document, each event must specify the namespace, event type, elements, and order of its elements. Using the TestTrackingEvent example, you would construct the XML representing an instance of the TestTrackingEvent as follows:
Note: Assume that testTrackingEvent is a well-formed instance of a TestTrackingEvent.
Using the schema keys from the TestTrackingEvent class, values are inserted into the XML document. Schema key/attribute value pairs correspond to XML elements in this way:
<schema Key>value</schema Key>
The helper class that creates XML for Behavior Tracking assumes that the elements inserted into an XML instance document are not deeply nested. Additionally, the toString() method is used to create a representation of the value object that is retrieved through the Event classes's getAttribute( String Key ) call. The contents of the string returned by invoking toString() on the value object must match the type specified in the event's schema document. The TestTrackingEvent retrieves values using the following keys in the order specified in the schemaKeys array:
The values for these keys are retrieved using the testTrackingEvent.getAttribute( <schema Key> ) call. The order in which the XML formatted key/value pairs are inserted into the instance document is specified by the constant schemaKeys array, which is defined and populated in the TestTrackingEvent class.
The steps assembled to create an XML instance document for the TestTrackingEvent are presented in Listing 15-11.
Listing 15-11 XML Instance Document Example
<TestTrackingEvent
xmlns="http://<your URI>/testtracking"
xmlns:xsi="http://www.w3.org/2000/10/XMLSchema-instance"
xsi:schemaLocation="http://<your URI>/testtracking TestTrackingEvent.xsd"
>
<event_date>XML time instant formatted event date</event_date>
<event_type>TestTrackingEvent</event_type>
<application>wlcsApp</application>
<session_id>theSessionIdValue</session_id>
<user_id>theUserIdValue</user_id>
<userPropertyOne>userPropertyOneValue</userPropertyOne>
<userPropertyTwo>userPropertyTwoValue</userPropertyTwo>
</TestTrackingEvent>
The XML creation is performed automatically when events arrive at the com.bea.p13n.tracking.listeners.BehaviorTrackingListener, which enables Behavior Tracking in WebLogic Portal. The Behavior Tracking listener is installed by adding it to the <EventService Listeners="..."> property in the application-config.xml file. For information on how to install a Behavior Tracking listener, seeHow to Enable Behavior Tracking.
Caution: You must be careful when defining the namespaces, XSD documents, and schema keys variables in custom Behavior Tracking event classes, especially if they will be persisted to the EVENT table. The method for creating and storing XML presented in this discussion exactly follows the variables and constants specified in the event class. You are free to develop other ways of creating and storing XML; this section is directed only at the process of persisting XML Behavior Tracking representations in the BEA EVENT table.
Note: The Event's date is retrieved using the Event class's getTimeStamp() call, which returns a Java primitive long typed value. That long must be converted into the type specified for the event_date element in the XSD schema document. The type in this case is time instant. Event date and event type the first two elements in all XML instance documents created through the BehaviorTrackingListener.
Creating Custom Behavior Tracking Event Listeners
To create a custom Behavior Tracking listener, in addition to or instead of the default BehaviorTrackingListener, follow the example presented in Writing the Custom Event Listener. Add the new event types to the custom listener's eventTypes array (for example, TestTrackingEvent). A given listener can listen for any number of event types that may or may not be Behavior Tracking events. The custom Behavior Tracking listener can be installed on either the synchronous or asynchronous side of the Event service, whichever is appropriate.
Writing Custom Event Generators
Once events are created, you must set up a mechanism for generating events in the application. Events may be generated from Pipeline components, input processors, JSP scriptlets, or JSP tags. Some Behavior Tracking events are generated from within WebLogic Portal software.
After determining the mechanism for generating events, Behavior Tracking events can be sent to the event system using the com.bea.p13n.tracking.TrackingEventHelper class. This class defines helper methods that pass events to the Event service. Listing 15-12 shows an example of passing the TestTrackingEvent.
Listing 15-12 Dispatching an Event
/*
* Create the event
*/
Event theEvent = new TestTrackingEvent( "<some session id>",
"<some user id> ",
new String("userPropertyOneValue"),
new Double( 3.14 ) );
/*
* Dispatch the event
*/
EventService eventService = TrackingEventHelper.getEventService();
TrackingEventHelper.dispatchEvent( eventService, theEvent );
Dispatching events Because the Event service is an EJB, before dispatching events, the Event service must be running in a WebLogic Server instance.
If dispatching multiple events, it is best to get an instance of the Event service and save it as an attribute in your class for reuse, as shown in the following code:
/**
* Access and start Event service
*/
private EventService eventService = com.bea.p13n.tracking.TrackingEventHelper.getEventService ( );
Note: There are three APIs for this. To decide which one to use, see the Javadoc at http://download.oracle.com/docs/cd/E13218_01/wlp/docs70/javadoc/index.html.
Now use that instance of the Event service to dispatch events, as follows:
/**
* Dispatch the event
*/
EventService eventService = TrackingEventHelper.getEventService();
TrackingEventHelper.dispatchEvent ( eventService, theEvent )
Debugging the Event Service
To debug the Event service, create a debug.properties file in the following directory:
<BEA_HOME>\weblogic700\portal\config\<YourDomain>\debug.properties
The contents of this file are shown in Listing 15-13.
Listing 15-13 Debugging the Event Service
usePackageNames: on
# Turns on debug for all classes under events
com.bea.p13n.events: on
# com.bea.p13n.events.internal.EventServiceBean: on
# Turns on debug for all classes under tracking
com.bea.p13n.tracking: on
# Or you can selectively turn on classes
com.bea.p13n.tracking.internal persistence: on
com.bea.p13n.mbeans.BehaviorTrackingListener: on
com.bea.p13n.tracking.listeners.BehaviorTrackingListener: on
com.bea.p13n.tracking.SessionEventListener: on
Registering Custom Events
This section contains basic information about registering custom events including background information about custom events, how to register events using the Events Editor in the BEA E-Business Control Center, and what you need to do when you make changes to custom events.
Note: You cannot change any of the standard events supplied with WebLogic Portal.
The creation of a custom event is a multiple-step process. The following list provides an overview of the process:
Note: You should have already completed steps 1 and 2.
When to Register an Event
When you create a custom event to use in a campaign, you must register the event. If your event is not used in a campaign, you do not need to register it. Registering a custom event lets the E-Business Control Center know that the custom event exists. Registering permits campaign developers using the E-Business Control Center to create scenario actions that refer to the event. Registering also identifies the event's properties.
Caution: Whenever you change the event code, you must update the event registration. Conversely, whenever you change the event registration, you must also update the event code. A possible ramification of event modification is that the scenario actions that refer to the event's properties may need to be modified.
Event Properties
The Event editor in the E-Business Control Center allows you to easily register a custom event. For the purpose of registering an event, you can consider an event property as a name-value pair. During the registration of a custom event, you specify the event's name, description, and one or more properties. Each property has a range, type of permissible value, and default value. The information you need to register for an event should be available from your Commerce Business Engineer (CBE) or Java developer.
The properties for a custom event includes the following information:
Note: When you set property values, you are not guaranteed that the property will adhere to these restrictions at run time. Events are not checked by the SchemaManager for adherence to a property schema. Therefore, you need to keep the event type definition and the event registration synchronized.
As the previous list suggests, a combination of property values are possible. The possible combinations of properties are listed here:
Instructions for Registering a Custom Event
To register a custom event, complete the following steps:
Figure 15-7 E-Business Control Center Window
Figure 15-8 Event Editor Window
Figure 15-9 Edit Property Window
Updating a Registered Custom Event
Whenever you make changes to a custom event's code, you should update that event's registration. Updating the registration lets the E-Business Control Center know about the changes in the custom event and aids campaign developers using the E-Business Control Center to modify any scenario actions (in campaigns) that refer to the event.
To update a custom event, complete the following steps.
Figure 15-11 Event Editor Window
Figure 15-12 Edit Property Window
Activating Behavior Tracking
To record how online visitors are interacting with your Web site, you can record event information in a database. These kinds of events are called Behavior Tracking events. E-analytics and e-marketing systems can then analyze these events offline to evaluate visitor behavior and transactional data.
Note: For information about how to configure a database for recording event data, see "Persisting Behavioral Tracking Data" in the Administration Guide at http://download.oracle.com/docs/cd/E13218_01/wlp/docs70/admin/sysadmin.htm#1194894.
This sections contains information on the following subjects:
Procedure for Activating Behavior Tracking
Before Behavior Tracking events can be recorded to a database, you must enable the Behavior Tracking listener. This is accomplished by adding a listener class.
Note: If the Event service does not exist as a service for your application, use WebLogic Server Administration Console to add it.
The following steps describe how to add a listener class in the Sample Portal. For your application, you would use similar steps.
Figure 15-13 WebLogic Server Administration Console—Event Service
Note: You must configure your database before activating Behavior Tracking. For information on how to do this, see "Persisting Behavior Tracking Data" in the Administration Guide at http://download.oracle.com/docs/cd/E13218_01/wlp/docs70/admin/sysadmin.htm#1194894.
Configuring the Behavior Tracking Service in WebLogic Server
Behavior Tracking events are placed in a buffer and then intermittently persisted to the Event tables in the database where they can be analyzed offline. An asynchronous service is used so that long-running event handlers can execute without delaying the application from a Web site visitor's perspective.
Note: Each Behavior Tracking event property must be configured in the WebLogic Server Administration Console.
Connection pool The buffered Behavior Tracking events are swept into the database using a pool of data connections. The default Data Source is weblogic.jdbc.jts.commercePool. You can use a different Data Source. To do this, create and configure the new Data Source (see Configuring a Data Source) and substitute the name of the default Data Source with the name of the new Data Source in the WebLogic Server Administration Console.
Properties The particular events that are persisted to the database are specified in the PersistEventTypes property. You can view and alter the list of the persisted events in the WebLogic Server Administration Console. The types in this list must match the type specified in the event; for example, the SessionBeginEvent has as its type the string "SessionBeginEvent".
Optimize performance The frequency of the sweeping of events from the buffer is controlled by the following properties the Behavior Tracking service:
You should tune these properties to optimize performance. A buffer sweep should be performed often enough that writing to the database is not too time consuming but not so frequent that the operation is wasteful.
Steps To configure the Behavior Tracking Service, take the following steps:
Notes: These steps provide information on how to optimize performance in the Sample Portal. For your application, you would use similar steps.
If the Event service does not exist as a service for your application, use WebLogic Server Administration Console to add it.
Note: If the Behavior Tracking and Event services do not exist for your application, use the WebLogic Server Administration Console to add them.
Configuring a Data Source
This section provides a brief description about configuring a new Data Source for a connection pool used for persisting events in the Sample Portal. For your application, you would use similar steps
To configure a new Data Source, take the following steps.
Note: For more information on using the WebLogic Server Administration Console, see the WebLogic Server documentation at http://download.oracle.com/docs/cd/E13222_01/wls/docs70/index.html.
|
|
|
|
||
 |
|
|
 |
 |
 |
|
||
