Interaction Management Guide
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:
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:
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
An event is an object that extends either the 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. |
|
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. |
|
The behavior tracking listener listens for all events that extend the 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. |
|
The campaign event listener listens for and handles all events, except those listed for exclusion in the 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:
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 For information on campaigns, see the Campaigns chapter in this guide. |
|
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, 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 |
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.
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:
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.
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.
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:
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.
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.
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.
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.
See Table 6-1 for details on how these properties are set. |
|
Page Flow: Session Login Event control API: Create an instance of the event in your code and dispatch it with Use the |
|
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.
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.
See Table 6-1 for details on how these properties are set. |
|
Page Flow: User Registration Event control API: Create an instance of the event in your code and dispatch it with |
|
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.
See Table 6-1 for details on how these properties are set. |
|
See Dispatching Events. |
|
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.
See Table 6-1 for details on how these properties are set. |
|
See Dispatching Events. |
|
|
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.
See Table 6-1 for details on how these properties are set. |
|
See Dispatching 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.
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.
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.
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.
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:
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.
See Table 6-1 for details on how these properties are set. |
|
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. |
|
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.
See Table 6-1 for details on how these properties are set. |
|
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 |
|
|
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.
See Table 6-1 for details on how these properties are set. |
|
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 |
|
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
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>
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>
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:
<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>
<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.
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.
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" );
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.
com.bea.p13n.tracking.listeners.BehaviorTrackingListener
Note: Synchronous listeners receive events immediately. Asynchronous listeners use a thread scheduler to receive events.
application-config.xml
file is updated. Behavior tracking is activated. No server restart or redeployment is required.Figure 6-2 Activating 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.
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.
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.
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.
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.
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:
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.
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.
com.bea.p13n.events.Event
class. For example:public class MyEvent
extends com.bea.p13n.events.Event
public static final String TYPE = "MyEvent";
public static final String FOO_ATTRIBUTE = "fooAttribute";
public static final String SESSION_ID = "session-id";
public static final String USER_ID = "user-id";
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));
Event
class constructor and pass the event type back to it:
super( TYPE )
;
setAttribute( FOO_ATTRIBUTE, fooAttributeValue );
setAttribute( SESSION_ID, session_id );
if( user_id != null )
setAttribute( USER_ID, user_id );
else
setAttribute( USER_ID, "unknown" );
wherefooAttributeValue
is the variable that stores the value you retrieved in your code (not shown here).
p13n_ejb.jar
in the classpath. For example:javac -classpath D:\bea\weblogic\<portalApp>\p13n_ejb.jar MyEvent.java
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.
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.
com.bea.p13n.tracking.events.TrackingEvent
class. For example:public class MyEventBT
extends com.bea.p13n.tracking.events.TrackingEvent
public static final String TYPE = "MyEventBT";
private static final String XML_NAMESPACE = "http://www.yourdomain.com/myschemas/tracking/mytrackingschema";
private static final String XSD_FILE = "mytrackingschema.xsd";
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";
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.
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));
TrackingEvent
constructor and pass the required arguments back to it in the required order:{
super(
TYPE,
session,
XML_NAMESPACE,
XSD_FILE,
localSchemaKeys,
request );
setAttribute( PAGE_LABEL, pageLabelValue );
setAttribute( SESSION_ID, session_id );
if( user_id != null )
setAttribute( USER_ID, user_id );
else
setAttribute( USER_ID, "unknown" );
}
p13n_ejb.jar
in the classpath. For example:javac -classpath D:\bea\weblogic\<portalApp>\p13n_ejb.jar MyEventBT.java
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.
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.
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:
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.
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:
localSchemaKeys[]
array.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"/>
After you create the schema, add it to your portal application's p13n_ejb.jar
file using the following steps.
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
.
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:
listeners.properties
file in wps.jar
) and calls the Campaign Service to evaluate and trigger campaign actions.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.
public class MyEventListener
implements EventListener
{
private String[] eventTypes = {"MyEvent", "ClickContentEvent"};
public MyEventListener()
{
}
public String[] getTypes()
{
return eventTypes;
}
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.
}
}
p13n_ejb.jar
in the classpath. For example:javac -classpath D:\bea\weblogic\<portalApp>\p13n_ejb.jar MyEventListener.java
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.
com.bea.p13n.events.custom.listeners.MyEventListener
Note: Synchronous listeners receive events immediately. Asynchronous listeners use a thread scheduler to receive 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 );
TrackingEventHelper
, which is used to dispatch the event.rde
.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.
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.
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.
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.
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