Interaction Management Guide

Events and Behavior Tracking

As users interact with a Web interface, such as logging in, clicking or viewing a graphic, clicking a button, navigating to another page in a portal, and so on, events are generated.

WebLogic Portal provides an events framework that lets you leverage events in many ways: to trigger campaigns, persist event data in the database, and provide other types of programmatic functionality when events occur.

Note: Interaction management events are distinct from portlet events, which provide a framework for inter-portlet communication.

Following are examples of functionality you can provide with the event framework:

• Capture the number of times users access a portal page.
• Determine how many users have registered in a portal. You could also create a campaign action that automatically sends each user a welcome e-mail when the registration event occurs.
• Identify which pieces of content are viewed or clicked.
• Determine which category of user (such as manager or regular employee) logs in to your human resources Intranet most often. You could also create a campaign action that displays a specific graphic when managers log in and displays another graphic when regular employees log in.

Each event is an instance of an Event object that is identified with a unique name, or type. Each event type can get and set specific attributes, depending on its function. In each of the previous examples, the event must capture specific information. For example, to capture the number of times users access a portal page, a ClickPage event might get and set the name of the page that was clicked; and to identify which pieces of content are viewed, a DisplayContent event might get and set the ID and type of each displayed content item.

After events set their attribute values, you can persist those values in any desired way. WebLogic Portal provides a default mechanism for persisting event attributes in a database as XML. When event data are stored in the database, you can mine that data to perform analytics, run reports, or even feed event data back into your applications. For example, you can create a portlet that runs SQL queries against the database and returns the number of times each portal page was hit. You can also develop your own persistence functionality. For example, you can store event data in a file, or you can write the data to database tables without structuring the data in XML.

Sometimes, events do not require attributes or persistence. Their only purpose could be to trigger some other type of functionality. For example, if you want to determine how many times a download link is clicked regardless of who clicked it, a ClickDownloadLink event (and an accompanying event listener) can increment a database field value by 1.

You can also make campaigns more powerful by using events in your campaign definitions. For example, you can send a user a predefined e-mail automatically when the user generates the UserRegistration event by registering in a portal; or display a personalized piece of content when an event with specific attribute values is generated.

This chapter describes the components of the event framework, helps you plan an event strategy by explaining the purpose and use of each piece of the framework, describes WebLogic Portal's predefined events, and provides guidance and instructions on using events in your applications.

This chapter includes the following sections:

• Overview of the Event Framework
• Planning an Event Strategy
• Predefined Events Provided by WebLogic Portal
• Enabling and Configuring Behavior Tracking
• Creating Custom Events
• Creating Custom Event Listeners
• Dispatching Events
• Using Events in Campaigns
• Debugging the Event Service

 

---

Overview of the Event Framework

The event framework, Figure 6-1, gives you the flexibility to handle events in many ways. The table following the figure describes the pieces of the framework.

Figure 6-1 The event framework

 

1	An event is an object that extends either the Event or TrackingEvent class. The event identifies itself to the Event Service with a unique name, or type, declares the attributes it will use, and passes the event type and the attributes to the base class constructor. Events can contain any types of attributes you want to capture. For example, you can capture the name of a page or a portlet that is selected for viewing; you can capture the name of a JSP in a Page Flow to gauge which JSPs are being hit most often, or to trigger a campaign when a specific JSP is viewed; you can capture information about content retrieved from the virtual content repository; you can capture product information when a user adds an item to a shopping cart. Behavior tracking events also declare the XML namespace and schema filename that the Event Service uses to store event attribute values in the database as XML. For each custom behavior tracking event you create, you should also create an XML schema.
2	Wherever you want to generate the event in your application, whether from a JSP, a Java class, or a page flow, create an instance of the event. In your code, set the attribute values the event needs, and pass them to the event as arguments in the order the event expects them. The argument order is defined in the event class. Tell the Event Service to dispatch the event. Dispatching an event tells all the interested event listeners that the event has occurred, causing them to perform their actions.
3	The behavior tracking listener listens for all events that extend the TrackingEvent class and are registered with the Behavior Tracking Service. The behavior tracking listener's function is to move the XML document of event attributes, created by the event and the XML schema, to a buffer. The Behavior Tracking Service then moves the XML document to the BT_EVENT table in the database in an interval you determine. You can retrieve behavior tracking data from the database for reporting or analytical purposes, such as determining the amount of traffic a page or portlet receives. By default, the behavior tracking listener is not registered with the Event Service. You must register the behavior tracking listener to enable behavior tracking, as described in Enabling and Configuring Behavior Tracking.
4	The campaign event listener listens for and handles all events, except those listed for exclusion in the wps.jar file's listeners.properties file. When an event occurs, the campaign event listener calls the Campaign Service. The Campaign Service takes a snapshot of the current HTTP request, and evaluates the data in the request against any campaigns you have created to see if any campaign actions need to be executed. Campaigns are completely dependent on events. If no events occur, the Campaign Service is never called, and no campaign actions are ever executed. In addition to the basic function of calling the Campaign Service with an event, you can also use events within campaign definitions by executing campaign actions if a specific event occurs or if an event has specific properties. For example, you can define a campaign in the following ways: If MyEvent occurs, show a specific piece of content. If MyEvent has a "published" property with a value greater than "2004," show a specific piece of content. In order to use events and event properties in campaign definitions, you must create an event property set for each event you want to use in campaigns (stored in your application's /data/events directory in WebLogic Workshop). An event property set contains the exact names of the attributes you are setting in your event. The campaign designer interface uses the event property set in drop-down fields that you use to create the campaign definition. For information on campaigns, see the Campaigns chapter in this guide.
5	Create a custom event listener only if you want to perform custom functionality when an event occurs. A custom listener tells the Event Service which events it is interested in—which events trigger it to perform its custom functionality. For example, with a custom event listener, you can implement your own persistence mechanism to store event attributes, or you can respond to an event in real time by modifying a user profile or displaying related products when a user clicks a product image. The base class you implement, EventListener, provides two methods: getTypes(), which lets the listener advertise which event types it is interested in, and handleEvent(), which lets you perform your custom functionality. A listener can listen for more than one event, whether the event is a custom event or any of WebLogic Portal's predefined events. In performing custom event handling, you have access to the event properties with the event's getAttribute() method.

 

 

---

Planning an Event Strategy

WebLogic Portal's event framework provides many options for generating and handling events, as described in the previous section. This section provides guidelines to help you determine the pieces of the event framework you want to use to implement the functionality you need.

When to Use WebLogic Portal's Predefined Events

WebLogic Portal provides many predefined behavior tracking events you can use in your applications, described in Predefined Events Provided by WebLogic Portal. Each event collects specific attributes and structures those attributes as XML, and the behavior tracking listener puts the XML in a buffer for insertion into BT_EVENT database table.

Most of the predefined events also have predefined event property sets in WebLogic Workshop, stored in the portal application's data/events directory. These property sets let you use events in your campaign definitions to trigger campaign actions when the events occur or when events have specific attribute values.

Use WebLogic Portal's predefined events when:

• The predefined events capture the attributes you want.
• You want to store event data as XML in the BT_EVENT table; and/or
• The events capture the attributes you want, but you want to handle the events in a customized way by creating your own event listener; and/or
• You want to use the events in your campaigns.

When to Create a Custom Event

If none of WebLogic Portal's predefined events captures the specific combinations of attributes you need, create a custom event. There are two types of custom events you can create: behavior tracking events and regular events.

Behavior Tracking Events

The only reason to create a custom behavior tracking event is when none of WebLogic Portal's predefined events captures the event attributes you want and you want to use WebLogic Portal's behavior tracking framework to persist event data as XML in the BT_EVENT table. You can use these events in campaigns and create a custom listener that performs special handling on the event, but unless you want to use the behavior tracking framework to store event data as XML, there is no reason to create a custom Behavior Tracking event.

If you do not want to use the Behavior Tracking service, create a custom regular event.

Regular Events

Create a custom regular event when none of WebLogic Portal's predefined events captures the event attributes you want and you do not want to use the Behavior Tracking service for persisting event data as XML in the BT_EVENT table.

Create a custom regular event when:

• You want to capture a specific set of attributes with an event and use that event to trigger campaigns; and/or
• You want to capture a specific set of attributes with an event and execute custom functionality when that event occurs (using a custom event listener).

When to Create a Custom Event Listener

WebLogic Portal provides two listeners: a campaign listener and a behavior tracking listener.

The campaign listener tells the Campaign Service when an event has occurred (with the exception of the ignored events in the wps.jar file's listener.properties file). The Campaign Service reads the current request and executes campaign actions if the request data matches the conditions of any of your campaigns. If your campaign definitions include any event conditions, which you were able to supply by way of event property sets, the Campaign Service evaluates those as well to determine if it must execute campaign actions.

The behavior tracking listener listens for only the behavior tracking events that are registered with the Behavior Tracking service. When it receives an event it is interested in, it moves the XML document for that event into a buffer for later persistence into the BT_EVENT table at an interval you determine.

Create a custom event listener if you want to execute functionality not provided by the campaign listener or the behavior tracking listener. For example, if you want to perform your own event data persistence, modify a user profile, redirect the user to another part of a page flow, or provide any other type of real-time response to the event, create a custom event listener that provides the functionality you want.

Deploying Custom Events, Listeners, and Property Sets

Creating custom events, listeners, and event property sets involves adding files to your application and updating your application classpath. If you are adding events and property sets to an application that is already deployed, these changes require application redeployment for the events and classpath updates, and running the Datasync Web Application to update the event properties in the database. For information on deployment and the Datasync Web application, see the Production Operations User Guide.

 

---

Predefined Events Provided by WebLogic Portal

This section provides details on using the predefined behavior tracking events provided by WebLogic Portal. The events capture different attributes and use the behavior tracking listener and the Behavior Tracking Service to persist the attributes as XML in the BT_EVENT table when they are generated, or dispatched. Behavior tracking must be enabled to persist the event attributes (as described in Enabling and Configuring Behavior Tracking). You can also use these events to trigger campaigns.

A few predefined events are provided for compatibility with legacy WebLogic Portal commerce applications: AddToCartEvent, PurchaseCartEvent, and RemoveFromCartEvent. These events were dispatched by pipeline components that were part of the flow of a commerce application. In previous versions of WebLogic Portal, application flows and catalog management used different frameworks for retrieving event property values and dispatching the events. If you want to dispatch these events in new commerce applications, you must create your own code and content management properties to set and get the event property values, and you must dispatch these events from your application code (such as from Page Flows and JSPs).

If you want to perform custom event handling when any of the predefined events is dispatched, create a custom event listener, as described in Creating Custom Event Listeners.

SessionLoginEvent

Use the SessionLoginEvent to dispatch an event when a user logs in to a portal (is authenticated).

If behavior tracking is enabled, the event property values are written to the BT_EVENT table in the database when the event is generated and the event is registered with the Behavior Tracking Service as a persisted event, as shown in Figure 6-3.

Properties	session-id user-id See Table 6-1 for details on how these properties are set.
How to dispatch	Use any of the following: Page Flow: Session Login Event control API: Create an instance of the event in your code and dispatch it with com.bea.p13n.tracking.TrackingEventHelper.dispatchSessionLoginEvent() or Use the PortalServletFilter to check for user logins (com.bea.p13n.servlets.PortalServletFilter, a registered filter in a portal Web project web.xml file that has the fireSessionLoginEvent parameter set to true by default).
Javadoc	com.bea.p13n.tracking.events.SessionLoginEvent com.bea.p13n.servlets.PortalServletFilter

 

SessionBeginEvent and SessionEndEvent

SessionBeginEvent and SessionEndEvent are generated automatically. A SessionBeginEvent is generated when a user accesses a Web site running on WebLogic Portal. A SessionEndEvent is generated when the session ends, such as when the user closes the browser or the session times out.

If behavior tracking is enabled, the event property values are written to the BT_EVENT table in the database when the events are generated and the event is registered with the Behavior Tracking Service as a persisted event, as shown in Figure 6-3.

SessionBeginEvent and SessionEndEvent do not have corresponding property sets in a portal application. By default, the campaign listener does not listen for these events, so they cannot be used to trigger campaigns. For more information, see How Campaigns are Triggered in the "Campaign" chapter of this guide.

 

UserRegistrationEvent

Use the UserRegistrationEvent to dispatch an event when a user registers in a portal (when the user is added to the user store programmatically; for example, with a registration portlet).

If behavior tracking is enabled, the event property values (in particular the user ID) are written to the BT_EVENT table in the database when the event is generated and the event is registered with the Behavior Tracking Service as a persisted event, as shown in Figure 6-3.

Properties	session-id user-id See Table 6-1 for details on how these properties are set.
How to dispatch	Page Flow: User Registration Event control API: Create an instance of the event in your code and dispatch it with com.bea.p13n.tracking.TrackingEventHelper.dispatchUserRegistrationEvent()
Javadoc	com.bea.p13n.tracking.events.UserRegistrationEvent

 

AddToCartEvent

Use AddToCartEvent to dispatch an event when a user adds an item to a shopping cart. This event lets you capture information such as currency type, quantity of the item being added, unit list price, and sku. These properties must be represented somehow in your shopping cart and content type to use this event.

If behavior tracking is enabled, the event property values are written to the BT_EVENT table in the database when the event is generated and the event is registered with the Behavior Tracking Service as a persisted event, as shown in Figure 6-3.

Properties	application-name currency quantity session-id sku unit-list-price user-id See Table 6-1 for details on how these properties are set.
How to dispatch	See Dispatching Events.
Javadoc	com.bea.commerce.ebusiness.tracking.events.AddToCartEvent

 

RemoveFromCartEvent

Use RemoveFromCartEvent to generate an event when a user removes an item from a shopping cart. This event lets you capture information such as currency type, quantity of the item being added, unit list price, and sku. These properties must be represented somehow in your shopping cart and content type to use this event.

If behavior tracking is enabled, the event property values are written to the BT_EVENT table in the database when the event is generated and the event is registered with the Behavior Tracking Service as a persisted event, as shown in Figure 6-3.

Properties	application-name currency quantity session-id sku unit-price user-id See Table 6-1 for details on how these properties are set.
How to dispatch	See Dispatching Events.
Javadoc	com.bea.commerce.ebusiness.tracking.events.RemoveFromCartEvent

 

PurchaseCartEvent

Use PurchaseCartEvent to dispatch an event when a user makes a purchase. This event lets you capture information such as currency type, order number, and total purchase price. These properties must be represented somehow in your shopping cart to use this event.

If behavior tracking is enabled, the event property values are written to the BT_EVENT table in the database when the event is generated and the event is registered with the Behavior Tracking Service as a persisted event, as shown in Figure 6-3.

Properties	application-name currency order-id session-id total-price user-id See Table 6-1 for details on how these properties are set.
How to dispatch	See Dispatching Events.
Javadoc	com.bea.commerce.ebusiness.tracking.events.PurchaseCartEvent

 

Rule Events

WebLogic Portal provides a Rule Event control that lets you generate a behavior tracking event whenever you fire a rule in a page flow using the Rules Executor control. The Rule Event control gets all necessary properties, including the names of the rule set and the rule that was fired.

If behavior tracking is enabled, the event property values are written to the BT_EVENT table in the database when the event is generated and the event is registered with the Behavior Tracking Service as a persisted event, as shown in Figure 6-3.

The Rule Event does not have a corresponding property set in a portal application. Rules are often used instead of campaigns, because they provide more flexibility and power; so creating a rule event property set to trigger a campaign when a rule is fired is not a likely scenario. However, if you want to create a rule property set to trigger a campaign when a rule is fired, create an event property set called RuleEvent.evt and add the following single, unrestricted String properties: ruleset-name and rule-name. For instructions on creating property sets, see Registering Custom Events in the WebLogic Workshop help system.

For instructions on using rules, see the Rule Event Control and the guide to Using Rules in Portal Applications.

DisplayCampaignEvent

If behavior tracking is enabled, a DisplayCampaignEvent is automatically generated when a campaign places a content item in a placeholder. The event property values are written to the BT_EVENT table in the database when the event is generated and the event is registered with the Behavior Tracking Service as a persisted event, as shown in Figure 6-3.

Properties	application-name campaign-id document-id document-type placeholder-id scenario-id session-id user-id
How to dispatch	This event is generated automatically whenever a campaign puts a content item in a placeholder.
Javadoc	com.bea.campaign.tracking.events.DisplayCampaignEvent

 

Display Content Events

WebLogic Portal provides a Display Content Event control and a <BehaviorTracking:displayContentEvent/> JSP tag that let you generate a behavior tracking event when you display a piece of content in a JSP.

See Table 6-1 for details on how get the document-id and document-type properties.

If behavior tracking is enabled, the event property values are written to the BT_EVENT table in the database when the event is generated and the event is registered with the Behavior Tracking Service as a persisted event, as shown in Figure 6-3.

A Display Content Event does not have a corresponding property set in a portal application. By default, the Campaign Service does not listen for these events, so they cannot be used to trigger campaigns. For more information, see How Campaigns are Triggered in the "Campaign" chapter of this guide.

Display Product Events

WebLogic Portal provides a <productTracking:displayProductEvent/> JSP tag that lets you generate a behavior tracking event when you display a product from your catalog.

See Table 6-1 for details on how get the application-name, category-id, document-id, document-type, and sku properties.

If behavior tracking is enabled, the event property values are written to the BT_EVENT table in the database when the event is generated and the event is registered with the Behavior Tracking Service as a persisted event, as shown in Figure 6-3.

A Display Product Event does not have a corresponding property set in a portal application. By default, the Campaign Service does not listen for these events, so they cannot be used to trigger campaigns. For more information, see How Campaigns are Triggered in the "Campaign" chapter of this guide.

ClickCampaignEvent

Use ClickCampaignEvent in conjunction with the ClickThroughEventFilter to generate an event when a user clicks a content item displayed by a campaign.

To enable content clicking, you must do the following:

• Include the appropriate entries in your portal Web project's web.xml and weblogic.xml files, as described in Generating Events for Content Clicks.
• Configure your content items with specific properties, described in the Setting up Content chapter of this guide.

If behavior tracking is enabled, the event property values are written to the BT_EVENT table in the database when the event is generated and the event is registered with the Behavior Tracking Service as a persisted event, as shown in Figure 6-3.

Properties	application-name campaign-id document-id document-type placeholder-id scenario-id session-id user-id See Table 6-1 for details on how these properties are set.
How to dispatch	Follow the instructions in Generating Events for Content Clicks for using the ClickThroughEventFilter, and configure the appropriate content properties in the virtual content repository, as described in described in the Setting up Content chapter of this guide.
Javadoc	com.bea.campaign.tracking.events.ClickCampaignEvent

 

ClickProductEvent

Use ClickProductEvent in conjunction with the ClickThroughEventFilter to generate an event when a user clicks a "product" content item. Product content items are typically those in a catalog or shopping cart. ClickProductEvent lets you capture information such as product category and sku. Both of those properties must be represented somehow in your content type to use this event.

To enable content clicking, include the appropriate entries in your portal Web project's web.xml and weblogic.xml files, as described in Generating Events for Content Clicks.

If behavior tracking is enabled, the event property values are written to the BT_EVENT table in the database when the event is generated and the event is registered with the Behavior Tracking Service as a persisted event, as shown in Figure 6-3.

Properties	application-name category-id document-id document-type session-id sku user-id See Table 6-1 for details on how these properties are set.
How to dispatch	Follow the instructions in Generating Events for Content Clicks for using the ClickThroughEventFilter. Use the <productTracking:clickProductEvent> JSP Tag to set the event attributes that are passed as parameters to the ClickThroughEventFilter, and set up the appropriate <a href> in your JSP. For sample code, see Use the ClickThroughEventFilter.
Javadoc	com.bea.commerce.ebusiness.tracking.events.ClickProductEvent

 

ClickContentEvent

Use the ClickContentEvent in conjunction with the ClickThroughEventFilter to generate an event when a user clicks any content item in a portal that was retrieved from the virtual content repository, but not as the result of a campaign.

To enable event generation on content clicking, include the appropriate entries in your portal Web project's web.xml and weblogic.xml files, as described in Generating Events for Content Clicks.

If behavior tracking is enabled, the event property values are written to the BT_EVENT table in the database when the event is generated and the event is registered with the Behavior Tracking Service as a persisted event, as shown in Figure 6-3.

Properties	document-id document-type session-id user-id See Table 6-1 for details on how these properties are set.
How to dispatch	Follow the instructions in Generating Events for Content Clicks for using the ClickThroughEventFilter. Use the <BehaviorTracking:clickContentEvent> JSP Tag or the Click Content Event control in a page flow to set the event attributes that are passed as parameters to the ClickThroughEventFilter. Set up the appropriate <a href> in your JSP. For sample code, see Use the ClickThroughEventFilter.
Javadoc	com.bea.p13n.tracking.events.ClickContentEvent

 

Generating Events for Content Clicks

WebLogic Portal provides predefined events that can be generated when a user clicks a content item in a portal. In particular, the following JSP tags enable content click events: <BehaviorTracking:clickContentEvent> and <productTracking:clickProductEvent>. The ClickCampaignEvent also generates content click events. To enable content to be clicked so that an event is dispatched to the Event Service, follow the instructions in these sections:

• Use the ClickThroughEventFilter
• Ensure the Event Service Is Registered in web.xml and weblogic.xml
• Campaign Clickthroughs

Use the ClickThroughEventFilter

Use the ClickThroughEventFilter whenever you use /ShowBinary in a URL. ShowBinary (which is mapped to the ShowPropertyServlet) displays binary Web content, such as graphics. Use /ShowBinary in the content URL in your JSPs. After you map the ClickThroughEventFilter to the /ShowBinary URL pattern, use /ShowBinary in your JSP as part of the URL in conjunction with a click event JSP tag. Then, when a user clicks the content, a click content event is generated by the ClickThroughEventFilter.

Note: Using /ShowBinary as the URL pattern is the most logical choice for showing binary content. However, you are not limited to using /ShowBinary.

To enable this capability, add the following filter and filter mapping to your portal Web project's web.xml file:

<filter>
    <filter-name>ClickThroughEventFilter</filter-name>
    <filter-class>
    com.bea.p13n.tracking.clickthrough.ClickThroughEventFilter
    </filter-class>
</filter>

<filter-mapping>
    <filter-name>ClickThroughEventFilter</filter-name>
    <url-pattern>/ShowBinary/*</url-pattern>
</filter-mapping>

JSP Example

Assuming you have added the filter mapping to your web.xml file, the following JSP code displays a content item from the virtual content repository (that has already been retrieved from an iterator, not shown) and provides the mechanism for click content event generation:

<!-- The JSP tag gets the documentId of a content item, which provides
     the ClickThroughEventFilter with the parameters it needs to
     generate an event. The id attribute stores the data retrieved
     by the tag. This JSP tag alone does not generate the event. -->

<BehaviorTracking:clickContentEvent documentId="<%= node.getName() %>" id="eventInfo" />

<!-- A URL variable uses /ShowBinary to provide the clickable link,
     which is mapped to the ClickThroughEventFilter. The eventInfo variable
     provides the ClickThroughEventFilter with the required event parameters
    when a user clicks the link. -->

<% String url = request.getContextPath() + "/ShowBinary"+node.getPath() + "?" + eventInfo;%>

<!-- Now if the user clicks the link, a ClickContentEvent is generated by
     the ClickThroughEventFilter. The ShowBinary servlet displays the
     content from the virtual content repository in its binary form
     (such as a graphic). -->

<a href="<%= url %>"><img src="<%=request.getContextPath() + "/ShowBinary" + node.getPath()%>" ></a>

Ensure the Event Service Is Registered in web.xml and weblogic.xml

The ClickThroughEventFilter, described in the previous section, references the Event Service, so you must make sure the Event Service is included in your portal Web project web.xml and weblogic.xml files.

When you create a new portal Web project, the following entries are included in web.xml and weblogic.xml by default. However, check to make sure your files contain these entries:

web.xml

<ejb-ref>
    <description>Event Service</description>
    <ejb-ref-name>ejb/EventService</ejb-ref-name>
    <ejb-ref-type>Session</ejb-ref-type>
    <home>com.bea.p13n.events.EventServiceHome</home>
    <remote>com.bea.p13n.events.EventService</remote>
</ejb-ref>

weblogic.xml

<ejb-reference-description>
    <ejb-ref-name>ejb/EventService</ejb-ref-name>
    <jndi-name>${APP_NAME}.BEA_personalization.EventService</jndi-name>
</ejb-reference-description>

Note: ${APPNAME} is a variable. Do not change it to a hard-coded application name.

Campaign Clickthroughs

To enable campaign clickthroughs that trigger the predefined ClickCampaignEvent, you must configure your content items with specific properties, as described in the Setting up Content chapter of this guide.

Providing Event Attribute Values

WebLogic Portal's predefined events set many of their attribute values automatically. However, there are attributes that you must set manually in your code. Table 6-1 describes the attributes needed by the predefined events and shows you the methods you can use to set the attributes in your code. You can also use these methods to set attributes in your custom events.

You can get some attributes from other generated events. For example, whenever a campaign displays a piece of content, a DisplayCampaignEvent is generated. The DisplayCampaignEvent sets, among others, an attribute called placeholder-id. If you want to set the placeholder-id for a custom event, you can get the attribute from the DisplayCampaignEvent using the getAttribute() method on that event. For example: DisplayCampaignEvent.getAttribute( "aPlaceholderId" );

Table 6-1 Getting attributes for predefined events

Event Attribute	How to get the attribute
application-name	The name of the enterprise application. All predefined events that use this attribute set it automatically. To set this attribute manually in a custom event, use the following method: com.bea.p13n.events.Event.getApplication()
campaign-id	The unique ID of a campaign. All predefined events that use this attribute set it automatically. To set this attribute manually in a custom event, use the following method: com.bea.campaign.CampaignInfo.getUniqueId()
category-id	The category that an item in the catalog belongs to. You must set this attribute manually. To get the category-id in the following way, your catalog must be built on the WebLogic Portal catalog API: com.beasys.commerce.ebusiness.catalog.service.category.CategoryManager.getItemCategories() If your catalog is built in any other way, get the category-id in the appropriate way.
currency	Gets the type of currency on an item. You must set this attribute manually. To get the currency in the following way, your commerce application must be built on the WebLogic Portal commerce API: com.beasys.commerce.axiom.units.Money.getCurrency() If your currency is set in any other way, get the currency in the appropriate way.
document-id	The unique virtual content repository ID of the retrieved content item. You could also get the unique document name. The campaign events set this attribute automatically. You must set it manually for all other events. Content events that have corresponding JSP tags provide a tag attribute. After you have retrieved a content item from the virtual content repository with a content selector, a campaign, a placeholder, or by any other means, use one of the following to get the document-id. com.bea.content.Node.getId() or getName() or Use the <cm:getProperty> JSP tag to get the cm_uid or cm_nodeName property.
document-type	Type is the name of the virtual content repository type, not the MIME type. The campaign events set this attribute automatically. You must set it manually for all other events. Content events that have corresponding JSP tags provide a tag attribute. After you have retrieved a content item from the virtual content repository with a content selector, a campaign, a placeholder, or by any other means, use com.bea.content.Node.getType() to retrieve the content's type.
order-id	The unique ID of a customer's order. To get the order-id in the following way, your commerce application must use the WebLogic Portal order framework. Use the following method: com.beasys.commerce.ebusiness.order.Order.getIdentifier() If your commerce application is built in any other way, get the order-id in the appropriate way.
placeholder-id	The unique ID of the content placeholder displaying the content. The predefined events that use this attribute set it automatically.
quantity	The quantity of an item in a shopping cart. To get the quantity in the following way, your commerce application must use the WebLogic Portal shopping cart framework. Use the following method: com.beasys.commerce.ebusiness.shoppingcart.ShoppingCartLine.getQuantity() If your shopping cart is built in any other way, get the quantity in the appropriate way.
scenario-id	The unique ID of a campaign scenario that contains the action that was executed. The predefined events that use this attribute set it automatically. To set it manually in a custom event, use the following method: com.bea.campaign.action.Action.getScenarioId()
session-id	The unique ID of the current session. This is retrieved automatically by the predefined events, which extend the TrackingEvent class, which uses javax.servlet.http.HttpSession.getId() and assigns the return value to the session-id property.
sku	The sku number of the catalog item. To get the sku in the following way, you must use the commerce framework to set sku numbers. Use the following method: com.bea.commerce.ebusiness.tracking.tags.ProductEventTag.getSku() If your catalog is built in any other way, get the sku in the appropriate way.
total-price	The total price of an order in a shopping cart. To get total-price in the following way, your commerce application must use the WebLogic Portal shopping cart framework. Use the following method: com.beasys.commerce.ebusiness.shoppingcart.ShoppingCart.getTotalPrice() If your shopping cart is built in any other way, get the total-price in the appropriate way.
unit-price unit-list-price	The unit price of an item in a shopping cart. To get unit-price or unit-list-price in the following way, your commerce application must use the WebLogic Portal shopping cart framework. Use the following method: com.beasys.commerce.ebusiness.shoppingcart.ShoppingCartLine.getUnitPrice() If your shopping cart is built in any other way, get the unit-price or unit-list-price in the appropriate way.
user-id	The ID of the authenticated user. This is retrieved automatically by the predefined events, which extend the TrackingEvent class, and the return value is assigned to the user-id property. You can also use the following method to get the user-id from the request: com.bea.p13n.usermgmt.SessionHelper.getUserId(request)

 

 

---

Enabling and Configuring Behavior Tracking

The default PointBase database in a WebLogic Portal domain (and the SQL scripts used to build a portal database for other database types) include behavior tracking tables that are ready to use for storing behavior tracking data. However, you must manually activate behavior tracking to use behavior tracking events.

To activate behavior tracking, register the BehaviorTrackingListener class with the Event Service using the following steps.

Note: This procedure assumes you are working in a development or testing environment with an exploded application. If you try to enable behavior tracking for an application that is in an EAR file, the configuration is saved only in memory, and behavior tracking will not be enabled if you restart the server. This is because the configuration needs to be written to the META-INF/application-config.xml file. That file is read-only in an EAR.

Start and log in to the WebLogic Administration Portal as a system administrator, and select Service Administration > Event Service.
In the Add field for Synchronous Listeners, as shown in Figure 6-2, enter the following class:

com.bea.p13n.tracking.listeners.BehaviorTrackingListener

Note: Synchronous listeners receive events immediately. Asynchronous listeners use a thread scheduler to receive events.

Click Update. The class appears in the Class Name list, and the application-config.xml file is updated. Behavior tracking is activated. No server restart or redeployment is required.

Figure 6-2 Activating behavior tracking




 

Configuring Behavior Tracking

By default, behavior tracking data is not written to the database the instant a behavior tracking event occurs. The events are stored in a buffer. You can determine how often behavior tracking data is moved to the database from the buffer.

To configure behavior tracking select Service Administration > Behavior Tracking Service in the WebLogic Administration Portal, as shown in Figure 6-3, and modify the settings, described in Table 6-2.

You must restart the server for your changes to take effect.

Figure 6-3 Configuring behavior tracking

 

Use the following field information for guidance.

Table 6-2 Behavior tracking settings

Maximum Buffer Size	Determines the maximum number of events stored in the buffer before the event data is written to the database. Default value: 100 events. All events are stored in the buffer, but only the events listed in the Persisted Event Types field are written to the database. All others are flushed from the buffer.
Buffer Sweep Interval	Determines how often the events buffer is checked to determine whether the events in the buffer should be persisted to the database. Two conditions trigger events to be moved from the buffer to the database: 1) The maximum buffer size has been reached, or 2) The maximum time allowed in the buffer (Buffer Sweep Maximum) has been exceeded. Default value: 10 seconds.
Buffer Sweep Maximum	Sets the maximum time in seconds before the events in the buffer are written to the database (and the non-persisted event types are flushed from the buffer). Default value: 120 seconds.

 

Leave the default values for Data Source JNDI Name (p13n.trackingDataSource) and Persistence Classname (null). These provide the default behavior for moving event data from the buffer to the BT_EVENT table in the database. For alternative persistence, see Storing Behavior Tracking Data in Other Ways.

For information on the Persisted Event Types field, see Creating a Behavior Tracking Event Class.

Performance Tuning

In your development or testing environment, start with a set of baseline values for Maximum Buffer Size, Buffer Sweep Interval, and Buffer Sweep Maximum. Try different values while testing peak site usage with your Web application until you find the ideal balance between the number of database operations and the amount of data being stored.

Storing Behavior Tracking Data in Other Ways

Behavior tracking event data, by default, is stored in the database in the BT_EVENT table. If you want to persist your event data in a different place or in a different way, such as to a different database table or to a file, create a custom event listener that provides the alternative persistence logic. For information on creating custom listeners, see Creating Custom Event Listeners.

Creating a Separate Database for Behavior Tracking Events

For improved performance, if you are heavily using behavior tracking, you can store behavior tracking data in a separate database. In the WebLogic Portal Database Administration Guide, there are explicit instructions for creating a separate behavior tracking database the chapters for each type of database.

 

---

Creating Custom Events

If none of WebLogic Portal's predefined events meets your needs, you can create your own custom events. For guidance on when to create custom events and what type to create, see Planning an Event Strategy.

Creating a custom event involves the following steps:

• Creating the Event Class
• Creating an XML Schema (Behavior Tracking Only)

Creating the Event Class

WebLogic Portal provides the two base event objects that work with the Event Service: Event and TrackingEvent. These base classes provide the necessary methods required by the Event Service.

When you create an event class you extend one of the base classes, declare the event attributes you want, and pass the event data (such as the event type) to the base class constructor.

This section provides instructions on creating custom regular events and custom behavior tracking events.

Creating a Regular Event Class

Create a custom regular event when none of WebLogic Portal's predefined events captures the event attributes you want and you do not want to use the Behavior Tracking service for persisting event data as XML in the BT_EVENT table. You can trigger campaigns with custom regular events and perform your own event handling if you create a custom event listener.

The following procedure shows you how to create an custom event class.

Note: You can also view the sample event class ResourceDisplayedEvent.java in the following file: http://download.oracle.com/docs/cd/E13218_01/wlp/docs81/interm/src/sample_events.zip.

Create a custom event:
• Create an event class that extends the com.bea.p13n.events.Event class. For example:

public class MyEvent

  extends com.bea.p13n.events.Event

• Declare the type (name) of the event as a String. For example:

public static final String TYPE = "MyEvent";

• Declare the event attribute names as keys that are passed back to the Event constructor. For example:

public static final String FOO_ATTRIBUTE = "fooAttribute";
public static final String SESSION_ID = "session-id";
public static final String USER_ID = "user-id";

• Create the event object:

public MyEvent(
    String fooAttributeValue, 
    String user_id,
    HttpServletRequest request,
    HttpSession session)

Note: If you use events to trigger campaigns, you must have a string called "user-id" that contains the user's profile name. You must also have a "request" attribute of type com.bea.p13n.http.Request. The request attribute, however can be added at runtime with:
event.setAttribute("request", new Request(request, true));

• Call the Event class constructor and pass the event type back to it:

super( TYPE );

• Declare the event attributes.

setAttribute( FOO_ATTRIBUTE, fooAttributeValue );
setAttribute( SESSION_ID, session_id );
if( user_id != null )
    setAttribute( USER_ID, user_id );
else
    setAttribute( USER_ID, "unknown" );
where fooAttributeValue is the variable that stores the value you retrieved in your code (not shown here).

Compile the event class. When you run javac to compile, use the -classpath option to put p13n_ejb.jar in the classpath. For example:

javac -classpath D:\bea\weblogic\<portalApp>\p13n_ejb.jar MyEvent.java

Put the compiled class in the server classpath (or in a JAR, and put the JAR in the classpath).

In WebLogic Workshop with your enterprise application open, select Tools > Application Properties. In the Application Properties window, select WebLogic Server, and scroll to the bottom of the window to add your path to the Server classpath additions list.

Now you can dispatch the event from a JSP, Java code, or a page flow, as described in Dispatching Events.

If you want to use the event in campaign definitions, create an event property set for the event, as described in Registering Events for Campaigns.

If you want to perform custom functionality when the event is generated, create a custom event listener that listens for the event, as described in Creating Custom Event Listeners.

Creating a Behavior Tracking Event Class

The only reason to create a custom behavior tracking event is when none of WebLogic Portal's predefined events captures the event attributes you want and you want to use WebLogic Portal's behavior tracking framework to persist event data as XML in the BT_EVENT table. You can use these events in campaigns and create a custom listener that performs special handling on the event, but unless you want to use the behavior tracking framework to store event data as XML, there is no reason to create a custom Behavior Tracking event. If you do not want to use the Behavior Tracking service, create a custom regular event.

Your behavior tracking event works in tandem with its own XML schema to store the event data as XML in the BT_EVENT database table. Information about that schema must be included in your event class, as described in the following steps.

The following procedure shows you how to create an custom behavior tracking event class.

Note: You can also view the sample event class ResourceDisplayedEventBT.java in the following file: http://download.oracle.com/docs/cd/E13218_01/wlp/docs81/interm/src/sample_events.zip.

Create a custom behavior tracking event:
• Create an event class that extends the com.bea.p13n.tracking.events.TrackingEvent class. For example:

public class MyEventBT

  extends com.bea.p13n.tracking.events.TrackingEvent

• Declare the type (name) of the event as a String. For example:

public static final String TYPE = "MyEventBT";

• Declare the XML_NAMESPACE key. This is the namespace URL used by your behavior tracking event's XML schema to uniquely identify it. For example:

private static final String XML_NAMESPACE = "http://www.yourdomain.com/myschemas/tracking/mytrackingschema";

• Declare the name of the XML schema file. For example:

private static final String XSD_FILE = "mytrackingschema.xsd";

• Declare the event attribute names as keys that are passed to the TrackingEvent constructor. For example:

public static final String SESSION_ID = "session-id";
public static final String USER_ID = "user-id";
public static final String PAGE_LABEL = "pageLabel";

• Declare the XML schema keys as an array.

The schema keys are Strings that are passed to the base TrackingEvent constructor. These keys are used to get the behavior tracking data that is put into the database. List the keys as an array of String objects.

private static final String localSchemaKeys[] =
{
    SESSION_ID, USER_ID, PAGE_LABEL
};

The localSchemaKeys order is important, because it corresponds to the order in which the XML schema needs the event properties for the XML output. An XML file will be invalid if elements are out of order.

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, which must not be null, is the WebLogic Server session ID that is created for every session object. The USER_ID is the username of the user who triggered the event.

• Create the event object with the properties you declared, along with the user-id. For example:

public MyEventBT(
    String pageLabel,
    String user_id,
    HttpServletRequest request,
    HttpSession session )

Note: If you use events to trigger campaigns, you must have a string called "user-id" that contains the user's profile name. You must also have a "request" attribute of type com.bea.p13n.http.Request. The request attribute, however can be added at runtime with:
event.setAttribute("request", new Request(request, true));

• Call the TrackingEvent constructor and pass the required arguments back to it in the required order:

{

super( 
    TYPE,
    session,
    XML_NAMESPACE,
    XSD_FILE,
    localSchemaKeys,
    request );

• Declare the event attributes:

setAttribute( PAGE_LABEL,  pageLabelValue );
setAttribute( SESSION_ID,  session_id );

if( user_id != null )
    setAttribute( USER_ID, user_id );
else
    setAttribute( USER_ID, "unknown" );
}

where pageLabelValue is the variable storing the value you retrieved in your code (not shown here).

Compile the event class. When you run javac to compile the event class, use the -classpath option to put p13n_ejb.jar in the classpath. For example:

javac -classpath D:\bea\weblogic\<portalApp>\p13n_ejb.jar MyEventBT.java

Put the compiled class in the server classpath (or in a JAR, and put the JAR in the classpath).

In WebLogic Workshop with your enterprise application open, select Tools > Application Properties. In the Application Properties window, select WebLogic Server, and scroll to the bottom of the window to add your path to the Server classpath additions list.

Register the behavior tracking event with the Behavior Tracking Service in the WebLogic Administration Portal. This tells the behavior tracking listener to handle this type of event.
In the WebLogic Administration Portal, select Service Administration > Behavior Tracking Service.
In the Behavior Tracking Service window (Figure 6-3), enter the name of your behavior tracking class in the Persisted Event Types list (such as MyEventBT), and click Update.
Create an XML schema that determines the structure of the XML document generated by the behavior tracking event. See Creating an XML Schema (Behavior Tracking Only).

If you want to use the event in campaign definitions, create an event property set for the event, as described in Registering Events for Campaigns.

If you want to perform custom functionality when the event is generated, create a custom event listener that listens for the event, as described in Creating Custom Event Listeners.

Creating an Event With a Scriptlet

You can create an event without writing an event class by using a scriptlet in a JSP. This technique is best suited for simple, non-behavior tracking events that are used to trigger campaigns. Using this technique for complex events clutters your JSP. For example, use this technique in a JSP that has a form that can supply values to event properties.

To create an event with a scriptlet:

Create an event property set in WebLogic Workshop. See Registering Events for Campaigns.
After you have created the event property set, open the JSP in which you want to create the event, and select the Source View tab.
In the WebLogic Workshop Application Window, drag the event property set file into the the location of the JSP where you want the event to occur; for example, after the submit button on a form. The scriptlet is generated automatically.

For example, if you create an event property set called MyEvent.evt that contains a single, unrestricted attribute called fooAttribute, the following scriptlet is generated when you drag the property set file into a JSP:

<%

// Generate the Event object here.
// If you have a custom Event subclass for your event type,
// change this code to use it instead

com.bea.p13n.events.Event event = new com.bea.p13n.events.Event("MyEvent");

// fooProperty should be a String

event.setAttribute("fooProperty", "");

// These attributes are standard to all Events.

event.setAttribute("request", new com.bea.p13n.http.Request(request, true));

event.setAttribute("user-id", com.bea.p13n.usermgmt.SessionHelper.getUserId(request));

// Dispatch the Event to the EventService.

com.bea.p13n.tracking.TrackingEventHelper.dispatchEvent(request, event);

%>

Notice that the scriptlet automatically gets the request and the user-id, which are required for triggering campaigns, and the code for dispatching the event. The dispatch code uses the behavior tracking API, but it also dispatches regular events.

You must supply the value for fooProperty, such as from the value of a form field.

If you want to perform custom functionality when the event is generated, create a custom event listener that listens for the event, as described in Creating Custom Event Listeners.

Creating an XML Schema (Behavior Tracking Only)

Behavior tracking events, by default, store their property values in the database as XML. For each type of behavior tracking event, the Event Service uses a specific XML schema to create the XML. When you create a custom behavior tracking event, you must also create an XML schema for the Behavior Tracking Service to use.

When creating an XML schema for a custom behavior tracking event, consider the following connection points between the schema and your event class:

• Filename - The value of the XSD_FILE key in your event class must match the name of the actual XSD file.
• Namespace - The value of the XSD_NAMESPACE key in your event class must match the targetNamespace attribute value in your XSD file.
• Property Order - The XSD file contains a list of event attributes you want to capture. The order in which these properties are listed in the XSD must match the order they are listed in your event class's localSchemaKeys[] array.

For example, if your event class contains this list of schema keys:

private static final String localSchemaKeys[] =
{
SESSION_ID, USER_ID, PAGE_LABEL_KEY
};

your XSD file must list those properties in the same order.

You can view the sample XSD file ResourceDisplayedEventBT.xsd in the following file: http://download.oracle.com/docs/cd/E13218_01/wlp/docs81/interm/src/sample_events.zip.

The XSD is mostly boilerplate. Simply change the targetNamespace and xmlns= attribute values to your namespace, and add your custom event attributes, in order.

You can view the XSDs for WebLogic Portal's predefined at the following location: weblogic81\p13n\lib\p13n_ejb.jar.

A user might not be associated with an event. In such a case, use the minOccurs="0" attribute for the user-id attribute in the XSD file. For example:

<xsd:element ref="user-id" minOccurs="0"/>

Packaging the Schema

After you create the schema, add it to your portal application's p13n_ejb.jar file using the following steps.

Back up your p13n_ejb.jar file by creating a copy of it and naming it something like p13n_ejb.orig.
In your application directory, temporarily add the lib/schema/<yourschema>.xsd directory/file.
Add the schema to p13n_ejb.jar. In a command window (that has the JAR utility in the environment), switch to the application directory and run the following command:

jar uvf p13n_ejb.jar lib\schema\<yourschema>.xsd

The schema is added to the JAR file. Redeploy p13n_ejb.jar.

 

---

Creating Custom Event Listeners

An event listener serves one purpose: When an event occurs that it is listening for, the listener performs some type of programmatic functionality. WebLogic Portal provides the following two listeners that handle events in specific ways:

• CampaignEventListener - Listens for all events (except those it is told to ignore in the listeners.properties file in wps.jar) and calls the Campaign Service to evaluate and trigger campaign actions.
• BehaviorTrackingListener - Listens for all events registered with the Behavior Tracking service (Figure 6-3) and puts data from behavior tracking events in a buffer, where the data is later moved into the BT_EVENT database table. (You must manually register this listener to activate behavior tracking, as described in Enabling and Configuring Behavior Tracking.)

If you create and register a custom behavior tracking event, that event is handled by the BehaviorTrackingListener and the CampaignEventListener. If you create a custom regular event, that event is handled by the CampaignEventListener.

However, there may be times when you want to provide more programmatic functionality when events occur, whether the events are custom events or WebLogic Portal's predefined events. For example, you may want to persist event data to a file or another database table; or show related products when a user clicks a product image; or modify a user's profile when the user submits a form. For these additional types of functionality, you must create custom event listeners.

WebLogic Portal provides a base event listener object called EventListener. This base class, which you must implement in your custom listener, provides two methods for listening for and responding to events:

• getTypes() - Tells the Event Service which types of events the listener is interested in.
• handleEvent() - Lets you insert the custom functionality you want to perform when the listener receives an event it is interested in.

This section shows you how to write a custom listener for one or more events. The listener can listen for regular events, behavior tracking events, or both.

Note: You can also view the sample event listener customEventListener.java in the following file: http://download.oracle.com/docs/cd/E13218_01/wlp/docs81/interm/src/sample_events.zip.

Your custom event listener must implement EventListener. For example:

public class MyEventListener
    implements EventListener
{

Define the event(s) that the listener will listen for. For example:

private String[] eventTypes = {"MyEvent", "ClickContentEvent"};

Create the listener:

public MyEventListener()
{
}

Pass the type of events listened for back to the base constructor. This tells the Event Service which events to send to this listener when the events occur:

    public String[] getTypes()
    {
        return eventTypes;
    }

Override the handleEvent() method to provide the programmatic functionality you want the listener to perform when the listened-for events occur:

    public void handleEvent( Event ev )
    {
        //Put your custom code here.
        //This code is executed when the events occur.
    }
}

Compile the event class. When you run javac to compile, use the -classpath option to put p13n_ejb.jar in the classpath. For example:

javac -classpath D:\bea\weblogic\<portalApp>\p13n_ejb.jar MyEventListener.java

Put the compiled class in the server classpath (or in a JAR, and put the JAR in the classpath).

In WebLogic Workshop with your enterprise application open, select Tools > Application Properties. In the Application Properties window, select WebLogic Server, and scroll to the bottom of the window to add your path to the Server classpath additions list.

Register the listener with the Event Service.
In the WebLogic Administration Portal, select Service Administration > Event Service.
In the Event Service window, enter the fully qualified class name in either the Synchronous or Asynchronous field. For example:

com.bea.p13n.events.custom.listeners.MyEventListener

Note: Synchronous listeners receive events immediately. Asynchronous listeners use a thread scheduler to receive events.

Click Update. The listener is registered with the Event Service. No server restart is required.

 

---

Dispatching Events

With events and listeners in place, you can generate, or dispatch those events in your JSPs, Java code, and page flows. Dispatching an event means having the Event Service send an event object to any listeners interested in the event. Those listeners, in turn, handle the events in their own ways.

In the sample events provided in http://download.oracle.com/docs/cd/E13218_01/wlp/docs81/interm/src/sample_events.zip, a sample event, ResourceDisplayedEventBT, is dispatched from two portal framework skeleton JSP files: book.jsp and page.jsp. The book.jsp skeleton is responsible for rendering portal book and page navigation (such as tabs), and the page.jsp skeleton provides the area for portlets to be displayed.

Inserted in each of these files is the code shown in Listing 6-1. This example uses code from page.jsp. The code dispatches a ResourceDisplayEventBT event when portlets are viewed on a page.

Listing 6-1 Dispatching an event from page.jsp

<%@ page import="com.bea.p13n.tracking.TrackingEventHelper,
                 examples.events.ResourceDisplayedEventBT" %>
...
ResourceDisplayedEventBT rde;
...
rde = new ResourceDisplayedEventBT( ppc.getLabel(),  // resourceId,
                                    portletTitle,    // resourceLabel
                                    "portlet",       // resourceType
                                    sessionId,
                                    userId,
                                    "true",  // portlet is being displayed
                                    request,
                                    session );
...
TrackingEventHelper.dispatchEvent( rde );

• The file imports the custom event class and the TrackingEventHelper, which is used to dispatch the event.
• The event class is assigned to the variable rde.
• An instance of the event is created, and the attributes retrieved from the JSP are passed in as event arguments in the same order that the event expects them. It does not matter what names are used in the arguments as long as they supply the type of information the event needs.
• The event is dispatched to the Event Service with the TrackingEventHelper.dispatchEvent( rde ) method.

The event is then sent to the listeners registered to receive it, and the listeners handle the event in their own ways. Figure 6-1 illustrates the event life cycle, and in this example, the skeleton JSP is item 2 in the diagram.

The section Creating an Event With a Scriptlet also describes how to dispatch an event for which you have created no event class.

Dispatching events when content is clicked requires special instructions, described in Generating Events for Content Clicks.

Some predefined events have their own dispatch methods. See Predefined Events Provided by WebLogic Portal.

 

---

Using Events in Campaigns

You can use events to activate the Campaign Service and to make your campaigns more powerful by triggering campaign actions based on events and their attribute values.

To use an event in a campaign, you do not have to explicitly tell the Campaign Service about your events. The campaign listener listens for all events that are not explicitly excluded in the listeners.properties file in wps.jar.

When an event occurs that the campaign listener is listening for, the listener calls the Campaign Service. The Campaign Service takes a snapshot of the current request and evaluates the request data against all the campaign rules you have defined to see if any actions need to be performed.

In addition, you can use events in campaigns in another way: as part of a campaign action. For example, you can define a campaign action that displays personalized content only if the user clicks the Home page in a portal (triggered by some sort of click page event). To use events as part of a campaign definition, you must create an event property set, as described in Registering Events for Campaigns.

An example of using an event in a campaign definition is illustrated in Figure 6-4, where a campaign scenario is going to be triggered if an event has specific property values (characteristics). When you add An event has specific characteristics to your campaign scenario and click the characteristics link in the campaign editor, you can select the event properties and determine which property values will trigger the campaign action to occur. The event property set you created enabled the property selection.

Figure 6-4 Using an event to trigger a campaign scenario

 

To exercise the most control with your campaign, especially when you want precise control over the personalized content that is displayed, create events that trigger campaign actions at the key places in your application where you want the precise control. For more information on controlling personalized content, see Combining Default Queries and Campaign Queries in Placeholders in the "Placeholders" chapter of this guide.

For information on creating campaigns, see the Campaigns chapter in this guide.

Registering Events for Campaigns

If you want to use a custom event to trigger a campaign, you must create an event property set. The properties you create for the event match the attribute names defined in your event class.

For example, the sample ResourceDisplayedEvent class uses the following properties: resourceId, resourceLabel, resourceType, session-id, user-id, and resourceSelected. In your event property set, you can define properties for any or all of those attributes, but the property names have to exactly match the event attribute names.

For instructions on creating event property sets, see Registering Custom Events in the WebLogic Workshop help system.

Changing Event Properties

If you create, modify, or delete event property sets after an application has already been deployed, you must update those property set definitions in the database using the WebLogic Portal Datasync Web application. For more information on the Datasync Web application, see the Production Operations User Guide.

 

---

Debugging the Event Service

To debug the Event Service, create the following file: weblogic81\portal\debug.properties.

Add the following to the file and modify the settings accordingly. These settings provide server console output for you to review.

usePackageNames: on
com.bea.p13n.cache: 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
# com.bea.p13n.tracking: on
com.bea.p13n.tracking.internal persistence: on
# Selectively turn on classes
com.bea.p13n.mbeans.BehaviorTrackingListerner: on
com.bea.p13n.tracking.listeners.BehaviorTrackingListerner: on
com.bea.p13n.tracking.SessionEventListerner: on