Oracle® Fusion Middleware Interaction Management Guide for Oracle WebLogic Portal 10g Release 3 (10.3.4) Part Number E14238-03 |
|
|
View PDF |
An Event is generated when a user interacts with a web interface. Events can include logging in, clicking or viewing a graphic, clicking a button, navigating to another page in a portal, and so on.
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 functionality when events occur.
Note:
Interaction Management events are different than portlet events, which provide a framework for interportlet communication. See the Oracle Fusion Middleware Portlet Development Guide for Oracle WebLogic Portal.The following examples show 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 logs in to your HR Intranet most often. Categories of users could include managers and regular employees. 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.
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:
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. 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 is 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 visited. 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.
Figure 9-1 shows the event framework, which gives you the flexibility to handle events in many ways. Table 9-1 describes the pieces of the framework.
Number from Figure 9-1 | Description |
---|---|
1 |
An event is an object that extends either the Events can contain whatever type 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 visited most often. You can trigger a Campaign when a specific JSP is viewed; you can capture information about content retrieved from the virtual content repository, or you can capture product information when a user adds an item to a shopping cart. Note: Page flows are a feature of Apache Beehive, which is an optional framework that you can integrate with WLP. See "Apache Beehive and Apache Struts Supported Configurations" in the Oracle Fusion Middleware Portal Development Guide for Oracle WebLogic Portal. 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. Note: Page flows are a feature of Apache Beehive, which is an optional framework that you can integrate with WLP. See "Apache Beehive and Apache Struts Supported Configurations" in the Oracle Fusion Middleware Portal Development Guide for Oracle WebLogic Portal. |
3 |
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 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 Section 9.7, "Enabling Behavior Tracking." |
4 |
The Campaign event listener listens for and handles all events, except excluded events listed in the Campaigns are completely dependent on events. If no events occur, the Campaign service is never called, and no Campaign actions are 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 Chapter 8. |
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 to monitor (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. See the guidelines in Section 2.4, "Planning Your Behavior Tracking Strategy" to determine the pieces of the event framework you need to implement.
This section contains the following topic:
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 Propagation Utility to update the event properties in the database. For deployment instructions, see the Oracle Fusion Middleware Production Operations Guide for Oracle WebLogic Portal.
WebLogic Portal provides predefined Behavior Tracking events. 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. You must enable Behavior Tracking to persist the event attributes (as described in Section 9.7, "Enabling Behavior Tracking"). You can also use these events to trigger Campaigns.
If you want to perform custom event handling when any of the predefined events is dispatched, create a custom event listener, as described in Section 9.9, "Creating Custom Event Listeners."
This section contains the following topics:
Use the SessionLoginEvent
to dispatch an event when a user logs into a portal and 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 9-3.
The SessionBeginEvent
and the 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 9-3.
The SessionBeginEvent
and the 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 on starting a Campaign, see Section 8.4, "Triggering a Campaign."
Use the UserRegistrationEvent
to dispatch an event when a user registers in a portal (when the user is added to the user store programmatically with a registration portlet, for example).
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 9-3.
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 9-3.
The RemoveFromCartEvent
generates 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 9-3.
The PurchaseCartEvent
dispatches 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 9-3.
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.
Note:
Page flows are a feature of Apache Beehive, which is an optional framework that you can integrate with WLP. See "Apache Beehive and Apache Struts Supported Configurations" in the Oracle Fusion Middleware Portal Development Guide for Oracle WebLogic Portal.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 9-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 Chapter 4.
For more information on using rules, see Chapter 10.
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 9-3.
Using the Display Content Event control with a <BehaviorTracking:displayContentEvent/>
JSP tag let you generate a Behavior Tracking event when you display a piece of content in a JSP.
See Table 9-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 9-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 Section 8.4, "Triggering a Campaign."
The <productTracking:displayProductEvent>
JSP tag lets you generate a Behavior Tracking event when you display a product from your catalog.
See Table 9-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 9-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 Section 8.4, "Triggering a Campaign."
The CampaignUserActivityEvent
dispatches an event when a generic Campaign event occurs. This event creates a new DisplayCampaignEvent
and associates users with specific Campaign and Scenario instances. These properties must be represented 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 9-3.
Using the ClickCampaignEvent
with the ClickThroughEventFilter
generates an event when a user clicks a content item displayed by a Campaign.
Perform the following steps to enable content clicking:
Include the appropriate entries in your portal web project's web.xml
and weblogic.xml
files, as described in Section 9.4, "Generating Events for Content Clicks."
Configure your content items with specific properties, as described in Chapter 3.
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 9-3.
Use the ClickProductEvent
with the ClickThroughEventFilter
to generate an event when a user clicks a product content item.
The 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 Section 9.4, "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 9-3.
Use the ClickContentEvent
with the ClickThroughEventFilter
to generate an event when a user clicks any content item 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 Section 9.4, "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 9-3.
WebLogic Portal provides predefined events that can be generated when a user clicks a content item in a portal. In particular, the <BehaviorTracking:clickContentEvent>
and the <productTracking:clickProductEvent>
JSP tags enable content click events. The ClickCampaignEvent
also generates content click events. To enable content to be clicked so that an event is dispatched to the Event service, use the ClickThroughEventFilter
, add the EventService
to the web.xml
file and the weblogic.xml
file, and enable Campaign clickthroughs.
This section contains the following topics:
Use the ClickThroughEventFilter
whenever you use /ShowBinary
pattern 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 with a click event JSP tag. Then, when a user clicks the content, a click content event is generated by the ClickThroughEventFilter
.
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>
To enable Campaign clickthroughs that trigger the predefined ClickCampaign Event
, you must configure your content items with specific properties, as described in Chapter 3.
Other predefined events track changes made to the virtual content repository or to the repository configuration. 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. You must enable Behavior Tracking to persist the event attributes (as described in Section 9.7, "Enabling Behavior Tracking").
The following events track repository changes: CampaignUserActivityEvent
, ContentConfigEvent
, ContentCreateEvent
, ContentDeleteEvent
, and ContentUpdateEvent
.
If you want to perform custom event handling when any of the predefined events is dispatched, create a custom event listener, as described in Section 9.9, "Creating Custom Event Listeners."
The ContentConfigEvent
dispatches a new event when a user makes a configuration change to the virtual content repository. This event lets you capture information, such as the action that was performed on the repository. The properties must be represented 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 9-3.
The ContentCreateEvent
dispatches an event when a user adds content to the virtual content repository. This event lets you capture information, such as the content type, the path where the new content was created, the content's status, and so on. The properties must be represented 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 9-3.
The ContentDeleteEvent
dispatches an event when a user removes content from the virtual content repository. This event lets you capture information, such as the content type, the path where the content existed before it was removed, the content's status, and so on. The properties must be represented 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 9-3.
The ContentDeleteEvent
dispatches an event when a user changes content from the virtual content repository. This event lets you capture information, such as the content type, the path where the content existed before it was updated, the content's status, and so on. The properties must be represented 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 9-3.
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 9-2 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 an attribute called placeholder-id. (It also sets other attributes.) 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 9-2 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: |
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: |
category-id |
The category that an item in the catalog belongs to. You must set this attribute manually. |
currency |
Gets the type of currency on an item. |
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:
or Use the |
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 |
order-id |
The unique ID of a customer's order. |
placeholder-id |
The unique ID of the content Placeholder displaying the content. The predefined events that use this attribute set it automatically. |
quantity |
The number of a specific items in a shopping cart. |
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: |
session-id |
The unique ID of the current session. This is retrieved automatically by the predefined events, which extend the |
sku |
The sku number of the catalog item. |
total-price |
The total price of an order in a shopping cart. |
unit-price unit-list-price |
The unit price of an item in a shopping cart. |
user-id |
The ID of the authenticated user. This is retrieved automatically by the predefined events, which extend the |
The default Derby 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. You can use the Administration Console or Oracle Enterprise Pack for Eclipse to enable Behavior Tracking. The tool you choose to enable Behavior Tracking depends on how you want to deploy your application.
Choose one of the following two ways to enable Behavior Tracking:
Administration Console – To make changes to your application at run-time, register the Behavior Tracking Listener in the Administration Console. This configuration information is written to the plan.xml
deployment file. See Section 9.7.1, "Enabling Behavior Tracking in the Administration Console" for instructions.
Oracle Enterprise Pack for Eclipse – To deploy your application to a new domain, enable Behavior Tracking by updating the p13n-config.xml
file for your application in Oracle Enterprise Pack for Eclipse and placing it in your <EAR>/META-INF
directory. (Oracle Enterprise Pack for Eclipse does not create a plan.xml
deployment file.) This configuration information is merged and saved with other configuration files from other library modules when you deploy your EAR file. See Section 9.7.6, "Enabling Behavior Tracking in Oracle Enterprise Pack for Eclipse" for instructions.
This section contains the following topics:
Section 9.7.1, "Enabling Behavior Tracking in the Administration Console"
Section 9.7.3, "Adjusting Behavior Tracking for Optimal Performance"
Section 9.7.4, "Storing Behavior Tracking Data in Other Ways"
Section 9.7.5, "Creating a Separate Database for Behavior Tracking Events"
Section 9.7.6, "Enabling Behavior Tracking in Oracle Enterprise Pack for Eclipse"
Use the Administration Console to update the plan.xml
deployment file for your application at run-time. See the Oracle Fusion Middleware Production Operations Guide for Oracle WebLogic Portal for more information on deployment plans.
If you are using a database other than Derby, see the Oracle Fusion Middleware Database Administration Guide for Oracle WebLogic Portal for instructions on creating a separate database for Behavior Tracking events.
Perform the following steps to activate Behavior Tracking by registering the BehaviorTrackingListener
class with the Event service:
Start the Administration Console and log in as a system administrator.
Choose Configuration & Monitoring > Service Administration.
In the Resource Tree, expand the Personalization folder and select Event Service.
In the Synchronous Listeners section, click Add Synchronous Listener.
Enter the following class in the Class Name field:
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 plan.xml
file is updated. Behavior Tracking is activated, as shown in Figure 9-2. You do not need to restart the server or redeploy your application.
Figure 9-2 The New Class Appears in the Class Name Field
By default, Behavior Tracking data is not written to the database immediately when 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.
Perform the following steps to determine how often Behavior Tracking data is moved to the database:
Start the Administration Console and log in as a system administrator.
Choose Configuration & Monitoring > Service Administration.
In the Resource Tree, expand the Personalization folder and select Behavior Tracking Service.
Click Configuration Settings for: Behavior Tracking Service. Figure 9-3 shows the Configuration Setting dialog box.
Modify the settings, as described in Table 9-1. Leave the default values for Data Source JNDI Name (the p13n.trackingDataSource
) and Custom Persistence Classname (null). These fields provide the default behavior for moving event data from the buffer to the BT_EVENT
table in the database. For alternative persistence, see Section 9.7.4, "Storing Behavior Tracking Data in Other Ways." For information on the Persisted Event Types field, see Section 9.8.1.2, "Creating a Behavior Tracking Event Class."
Click Update.
Restart the server for your changes to take effect.
Use Table 9-3 when you set your Behavior Tracking settings.
Table 9-3 Behavior Tracking Settings
Setting | Description |
---|---|
Maximum Buffer Size |
Determines the maximum number of events stored in the buffer before the event data is written to the database. The default value is 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. The default value is 10 seconds. |
Buffer Sweep Maximum Time |
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). The default value is 120 seconds. |
This section contains the following topics:
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.
Tip:
If you do not use Behavior Tracking, you should disable Event services. See Section 9.14, "Disabling Behavior Tracking."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 Section 9.9, "Creating Custom Event Listeners."
If you are using Behavior Tracking, you can improve performance by storing Behavior Tracking data in a separate database. The Oracle Fusion Middleware Database Administration Guide for Oracle WebLogic Portal contains instructions for creating a separate Behavior Tracking database for each type of database.
If you plan to deploy your application to a new domain, you should enable Behavior Tracking in Oracle Enterprise Pack for Eclipse. This Behavior Tracking configuration information is merged with other configuration files from other library modules. You can place the updated p13n-config.xml
file in source control to use when you deploy other applications. See the Oracle Fusion Middleware Production Operations Guide for Oracle WebLogic Portal for more information on deployment.
For example, you can add event types for the listener to the configuration file, as shown in Example 9-1. This technique accomplishes the same result as adding the event types through the Administration Console, as explained in Section 9.13, "Tracking Content Changes." See also Section 9.5, "Generating Content Events" for information on the content event types.
Example 9-1 Adding Event Types to a P13N Configuration File
... <behavior-tracking> <persisted-event-type>ClickContentEvent</persisted-event-type> <persisted-event-type>DisplayContentEvent</persisted-event-type> <data-source-jndi-name>p13n.trackingDataSource</data-source-jndi-name> </behavior-tracking> ...
Perform the following steps to enable Behavior Tracking when deploying your application to a new domain:
Start Oracle Enterprise Pack for Eclipse and create a p13n-config.xml
file in your <EAR>/META-INF
directory or copy an existing file to your project.
Enter your configuration details and save the file. Saving the p13n-config.xml
file combines this information with your other library module configuration files. This appended configuration file can be used when you deploy other applications.
If you want to redeploy to the same application, right-click the server in the Servers tab and choose Publish.
Copy the p13n-config.xm.xml
file into your source control system.
Tip:
If you use Oracle Enterprise Pack for Eclipse to remove an application from a domain, the deployment plan is also removed.If WebLogic Portal's predefined events do not capture the specific combinations of attributes you need, you can create your own custom events. You can create two types of custom events: Behavior Tracking events and regular events.
For guidance on custom events and what type to create, see Section 2.4.2, "Understanding When to Create a Custom Event" and Section 2.4.1, "Understanding When to Use a Predefined Event." Creating a custom event involves creating the Event class and creating the XML Schema.
This section contains the following topics:
WebLogic Portal provides the two base event objects that work with the Event Service: com.bea.p13n.events.Event
and com.bea.p13n.tracking.events.TrackingEvent
. These base classes provide the necessary methods required by the Event Service. You can use either of these classes as the superclass when creating your event class as described in Step 2.
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 capture 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 steps involve creating am EJB or utility project, which is generally used to develop general-purpose Java code that is not directly part of special entities.
The steps in this chapter refer to the \src
folder in the Package Explorer View. Your src
directory might be named differently.
Perform the following steps to create a custom event class:
Create an EJB or utility project in Oracle Enterprise Pack for Eclipse by performing the following steps:
In the Portal Perspective, choose File > New > Project.
In the New Project - Select a Wizard window, expand the EJB folder and select WebLogic EJB Project or expand the J2EE folder and select Utility Project. Click Next.
Enter a name for the EJB or utility project and ensure that the Use default check box is selected. Select the Add project to an EAR check box and click Next, as shown in Figure 9-4.
Select the facets (including Portal Application Services) that you want to enable and click Finish.
Your new EJB or utility project is automatically associated with your EAR project. For more information on EJB projects, see the Oracle Fusion Middleware Portal Development Guide for Oracle WebLogic Portal.
Make a new Java class by performing the following steps:
Select your web project in Package Explorer View and choose File >New > Other.
In the New - Select a Wizard dialog, expand the Java folder, select Class, and click Next.
In the New Java Class - Java Class dialog, enter a Name for the new class and for the Superclass. Select the Constructors from superclass check box and the Inherited abstract methods check box and click Finish. See Figure 9-5.
Figure 9-5 Enter the Class Name and Superclass
The new class appears in the \src
directory of your portal web project.
Perform the following steps to declare event attribute names and create the event object for the new Java class:
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. For example:
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 the following code: event.setAttribute("request", new Request(request, true));Add a constructor, such as the one below, and pass the event type back to it:
super( TYPE );
Declare the event attributes with the following code:
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).
The Java files in the \src folder will be compiled the normal way and deployed as part of the application. You can dispatch the event from a JSP, Java code, or a Page Flow, as described in Section 9.10, "Dispatching Events." If you want to use the event in Campaign definitions, create an event property set for the event, as described in Section 9.11.1, "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 Section 9.9, "Creating Custom Event Listeners."
Note:
Page flows are a feature of Apache Beehive, which is an optional framework that you can integrate with WLP. See "Apache Beehive and Apache Struts Supported Configurations" in the Oracle Fusion Middleware Portal Development Guide for Oracle WebLogic Portal.Create a custom Behavior Tracking event if none of WebLogic Portal's predefined events captures the event attributes you want, and you need 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, you do not need to create a custom Behavior Tracking event. If you do not want to use the Behavior Tracking service, create a custom regular event as described on Section 9.8.1.1, "Creating a Regular Event Class."
Your Behavior Tracking event works 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 steps involve creating a utility project, which is generally used to develop general-purpose Java code that is not directly part of special entities, such as web services, controls, or EJBs.
The steps in this chapter refer to the src
folder in the Package Explorer View. Your src
directory might be named differently.
Perform the following steps to create a Behavior Tracking event class:
Create an EJB project in Oracle Enterprise Pack for Eclipse by performing the following steps:
In the Portal Perspective, choose File > New > Project.
In the New Project - Select a Wizard window, expand the EJB folder and select WebLogic EJB Project. Click Next.
In the New WebLogic EJB Project dialog, enter a name for the EJB project and ensure that the Use default check box is selected. Select the Add project to an EAR check box and click Next.
In the New Java Utility Module - Select Project Facets dialog, select the facets that you want to enable and click Finish.
Your new EJB project is automatically associated with your EAR project. For more information on EJB projects, see the Oracle Fusion Middleware Portal Development Guide for Oracle WebLogic Portal.
Make a new Java class by performing the following steps:
Select your web project in Package Explorer View and choose File >New > Other.
In the New - Select a Wizard dialog, expand the Java folder, select Class, and click Next.
In the New Java Class - Java Class dialog, enter a Name for the new class and for the Superclass. Select the Constructors from superclass check box and the Inherited abstract methods check box and click Finish. See Figure 9-6.
Figure 9-6 Enter the Class Name and Superclass
The new class appears in the \src
directory of your portal web project.
Perform the following steps to declare event attribute names and create the event object for the new Java class:
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 user name of the user who triggered the event.
Create the event object. For example:
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 the following code: event.setAttribute("request", new Request(request, true));Call the TrackingEvent
constructor and pass the required arguments back to it in the required order. For example:
{ super( TYPE, session, XML_NAMESPACE, XSD_FILE, localSchemaKeys, request );
Declare the event attributes. For example:
setAttribute( PAGE_LABEL, pageLabelValue ); setAttribute( SESSION_ID, session_id ); if( user_id != null ) setAttribute( USER_ID, user_id ); else setAttribute( USER_ID, "unknown" ); }
The pageLabelValue
is the variable storing the value you retrieved in your code (not shown here).
Register the Behavior Tracking event with the Behavior Tracking service in the WebLogic Portal Administration Console. This event tells the Behavior Tracking listener to handle this type of event.
Start the Administration Console.
In the Administration Console, choose Configuration & Monitoring > Service Administration.
In the Resource Tree, expand the Personalization folder and select Behavior Tracking Service.
In the Configure tab click Configure Settings for: Behavior Tracking Service.
Enter the name of your Behavior Tracking class in the Custom Persistence Classname field (such as behtrackingclass
).
Click Update.
Create an XML schema that determines the structure of the XML document generated by the Behavior Tracking event. See Section 9.8.2, "Creating an XML Schema for Behavior Tracking." If you want to use the event in Campaign definitions, create an event property set for the event, as described in Section 9.11.1, "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 Section 9.9, "Creating Custom Event Listeners."
The Java files in the \src
folder will be compiled the normal way and deployed as part of the application. You can dispatch the event from a JSP, Java code, or a Page Flow, as described in Section 9.10, "Dispatching Events." If you want to use the Behavior Tracking event in Campaign definitions, create an event property set for the event, as described in Section 9.11.1, "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 Section 9.9, "Creating Custom Event Listeners."
Note:
Page flows are a feature of Apache Beehive, which is an optional framework that you can integrate with WLP. See "Apache Beehive and Apache Struts Supported Configurations" in the Oracle Fusion Middleware Portal Development Guide for Oracle WebLogic Portal.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. You should use this technique in a JSP that has a form that can supply values to event properties.
Perform the following steps to create an event with a scriptlet:
In the Portal Perspective in Oracle Enterprise Pack for Eclipse, create an event property set. For instructions, see Section 9.11.1, "Registering Events for Campaigns."
After you have created the event property set, open the JSP in which you want to create the event.
Drag the event property set file into 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); %>
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, which could come from the value of a form field.
Save your work by choosing File > Save.
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 Section 9.9, "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:
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, your XSD file must list those properties in the same order:
private static final String localSchemaKeys[] = { SESSION_ID, USER_ID, PAGE_LABEL_KEY };
When you use XSD, you need to change only 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 events at the following location: <MW_HOME>\user_projects\workspaces\workshop\.metadata\.plugins\ com.bea.workshop.wls.core\libraries\p13n-app-lib_10.3.2_10.3.2\1\APP-INF\lib\p13n_app.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_app.jar
file using the following steps.
Back up your p13n_app.jar
file by creating a copy of it and naming it p13n_ejb.orig
, for example.
In your application directory, temporarily add the <yourschema>.xsd
file to the lib/schema/
directory.
Add the schema to the p13n_app.jar
file. 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_app.jar lib\schema\<yourschema>.xsd
The schema is added to the JAR file.
Redeploy the p13n_app.jar
file.
An event listener serves one purpose: when an event occurs for which the listener is listening, 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 the wps.jar
file) and calls the Campaign service to evaluate and trigger Campaign actions.
BehaviorTrackingListener – Listens for all events registered with the Behavior Tracking service and puts data from Behavior Tracking events in a buffer, where it is later moved into the BT_EVENT
database table. (You must manually register this listener to activate Behavior Tracking, as described in Section 9.7, "Enabling Behavior Tracking." For example, you could create a custom event listener that listens for the SessionLoginEvent
, SessionBeginEvent
, and SessionEndEvent
. You can add the user-id field of these events to a list to keep track of who has logged in.
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, 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:
The getTypes()
method – Tells the Event service which types of events that interest the listener.
The handleEvent()
method – Lets you insert the custom functionality you want to perform when the listener receives an event that interests it.
The steps to create a custom event listener involve creating a utility project, which is generally used to develop general-purpose Java code that is not directly part of special entities, such as web services, controls, or EJBs. Note that you can also use an EJB project (a new one or an existing one).
Note:
If you try to access a local EJB with an EventListener, the attempt will fail in the JNDI lookup. For this scenario, use a Remote EJB interface instead.The steps in this chapter refer to the \src
folder in the Package Explorer View. Your src
directory might be named differently.
Perform the following steps to create a custom event listener for regular events or Behavior Tracking events:
Create a utility project in Oracle Enterprise Pack for Eclipse by performing the following steps.
Note:
You can also use an EJB project. You can either create a new EJB project or use an existing one.In the Portal Perspective, choose File > New > Project.
In the New Project - Select a Wizard window, expand the J2EE folder and select Utility Project. Click Next.
In the New Java Utility Module - Utility Module dialog, enter a name for the utility project and ensure that the Use default check box is selected. Select the Add project to an EAR check box and click Next.
In the New Java Utility Module - Select Project Facets dialog, select the facets that you want to enable and click Finish. (If you select the Portal Application Services and/or Portal Customizations Framework facet, you can skip Step 2 and proceed to Step 3.)
Your new utility project is automatically associated with your EAR project. For more information on utility projects, see the Oracle Fusion Middleware Portal Development Guide for Oracle WebLogic Portal.
To ensure that the project sees the p13n classes as the server will see them, add the WebLogic Portal Server and the p13n-app-lib
library module CLASSPATH containers to the project. Perform the following steps:
Note:
It is unnecessary to perform Step 2 if you chose the Portal Application Services and/or Portal Customizations Framework facet in Step 1-d.In Package Explorer, right-click the portal utility project you created and choose Properties.
In the Properties dialog, select Java Build Path and select the Libraries tab.
Click Add Library.
In the Add Library dialog, select Oracle WebLogic Portal Server as the library type and click Next.
In the Add Library - Oracle WebLogic Portal Server dialog, configure the server CLASSPATH entries by selecting All Configured entries and clicking Finish.
In the Properties dialog, click Add Library in the Libraries tab.
In the Add Library dialog, select WebLogic Library Module and click Next.
In the Add Library - Library Module dialog, click Browse and select p13n-app-lib and click OK. The Specification Version, and Implementation Version fields are populated. Select the Allow newer versions check box and click Finish.
In the Properties dialog, click OK.
Make a new Java class by performing the following steps:
Select your web project in Package Explorer View and choose File >New > Other.
In the New - Select a Wizard dialog, expand the Java folder, select Class, and click Next.
In the New Java Class - Java Class dialog, enter a Name for the new class and for the Superclass. For example, a class name could be MyEventListener
. Select the Constructors from superclass check box and the Inherited abstract methods check box and click Finish.
The new class appears in the \src
directory of your portal web project.
Perform the following steps to define the events for which the listener will listen, declare event attribute names, and create the event object for the new Java class:
Your custom event listener must implement EventListener
. For example:
public class MyEventListener implements EventListener {
Define the events for which the listener will listen. For example:
private String[] eventTypes = {"MyEvent, ClickContentEvent"};
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. } }
The Java files in the \src
folder will be compiled the normal way and deployed as part of the application. You can dispatch the event listener from a JSP, Java code, or a Page Flow, as described in Section 9.10, "Dispatching Events." If you want to use the event listener in Campaign definitions, create an event property set for the event, as described in Section 9.11.1, "Registering Events for Campaigns."
Note:
Page flows are a feature of Apache Beehive, which is an optional framework that you can integrate with WLP. See "Apache Beehive and Apache Struts Supported Configurations" in the Oracle Fusion Middleware Portal Development Guide for Oracle WebLogic Portal.Register the listener with the Event service by performing the following steps.
In the Administration Console, choose Configuration & Monitoring > Service Administration.
In the Resource Tree, expand the Personalization folder and select Event Service.
In the Browse tab, click Add Synchronous Listener or Add Asynchronous Listener.
Enter the fully qualified class name. 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. You do not need to restart the server.
With events and listeners in place, you can dispatch those events in your JSPs, Java code, and Page Flows. Dispatching an event means that the Event service sends an event object to any listeners interested in the event. Those listeners, in turn, handle the events in their own ways.
Note:
Page flows are a feature of Apache Beehive, which is an optional framework that you can integrate with WLP. See "Apache Beehive and Apache Struts Supported Configurations" in the Oracle Fusion Middleware Portal Development Guide for Oracle WebLogic Portal.For example, a sample event called 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.
The code shown in Example 9-2 is inserted in each of the book.jsp
and page.jsp
. files. This example uses code from the page.jsp
file. The code dispatches a ResourceDisplayEventBT
event when portlets are viewed on a page.
Example 9-2 Dispatching an Event from a JSP Page
<%@ page import="com.bea.p13n.tracking.TrackingEventHelper, examples.events.ResourceDisplayedEventBT" %> ... ResourceDisplayedEventBT rde; ... ResourceDisplayedEvent rde = new ResourceDisplayedEvent( ppc.getLabel(), portletTitle, "portlet", sessionID, userId, "true", // portlet is being displayed request, session ); // New mechanism for dispatching an event in 9.2: EventService es = TrackingEventHelper.getEventService(); TrackingEventHelper.dispatchEvent(es, rde); ...
The code performs the following actions:
The file imports the custom event class and the TrackingEventHelper
, which is used to dispatch the event.
The event class is assigned to the rde variable.
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 9-1 illustrates the event life cycle, and in this example, the skeleton JSP is Item 2 in the diagram.
Section 9.8.1.3, "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, as described in Section 9.4, "Generating Events for Content Clicks." Some predefined events have their own dispatch methods. See Section 9.3, "Using Predefined Events."
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.
When you 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 the wps.jar
file.
When an event occurs for which the Campaign listener is listening, 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 Section 9.11.1, "Registering Events for Campaigns."
An example of using an event in a Campaign definition is illustrated in Figure 9-7, where a Campaign scenario is 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 9-7 Using an Event to Trigger a Campaign Scenario
To control your Campaign, especially when you want personalized content to display, create events that trigger Campaign actions at the key places in your application. For more information on controlling personalized content, see Section 14.4, "Managing Placeholders for Optimal Performance." For instructions on creating a Campaign, see Section 8.2, "Building a Campaign."
This section contains the following topic:
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 must exactly match the event attribute names.
For instructions on creating event property sets, see Section 9.8, "Creating Custom Events." For instructions on registering event property sets, see Section 9.7, "Enabling Behavior Tracking."
If you create, modify, or delete event property sets after an application is deployed, you must update those property set definitions in the database using the Propagation Utility. For more information, see the Oracle Fusion Middleware Production Operations Guide for Oracle WebLogic Portal.
You can debug the Event service and review the console output.
Perform the following steps to debug the event service:
To debug the Event service, create debug.properties
in a directory similar to the following: <MW_HOME>
\user_projects\domains\
<myDomain>
.
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.BehaviorTrackingListener: on com.bea.p13n.tracking.listeners.BehaviorTrackingListener: on com.bea.p13n.tracking.SessionEventListener: on
In Oracle Enterprise Pack for Eclipse, double-click the server in the Servers tab and uncheck the Launch WebLogic server in Eclipse console check box. Close the Server Overview tab and click Yes to save your changes. Right-click the server name and choose Restart to start the server and run debugging from a command prompt.
Tip:
Events will fire for a content repository that was upgraded to 10.x (unless you turned event tracking turned off at the repository level). Events can include repository configuration changes, as well as content updates, additions, and deletions to the repository. See the Oracle Fusion Middleware Upgrade Guide for Oracle WebLogic Portal for more information on performing an upgrade.You can use content events to track content changes to your virtual content repository and modifications to the repository's configuration. Content changes include who added, updated, or deleted content or content properties and the date and time the change was made in the repository. You can also track who performed the changes (including the date and time the changes were made) to the repository's configuration, its content types, or content workflow. For more information on these events, see Section 9.5, "Generating Content Events."
You could also configure a content event to watch for content changes and then perform an action. For example, when a user adds a resume document to the content repository, an e-mail is sent to the HR Director.
These content events are saved in the Behavior Tracking database for historical tracking. For more information on content management, see the Oracle Fusion Middleware Content Management Guide for Oracle WebLogic Portal.
Perform the following steps to track content changes:
Start the Administration Console.
Choose Configuration & Monitoring > Service Administration.
In the Resource Tree, expand the Personalization folder and select Event Service.
Click Add Synchronous Listener.
Enter the listener name in the Class Name field. To capture content repository changes, enter com.bea.p13n.tracking.listeners.BehaviorTrackingListener
. See Figure 9-8.
Figure 9-8 Identify the Behavior Tracking Listener
Click Update.
In the Resource Tree, select Behavior Tracking Service.
In the Configure tab, click Add Event Type, as shown in Figure 9-9.
In the Persisted Event Type field, enter the events for the content change you want to track. For example, you could add the ContentCreateEvent
to determine new content that was added to the content repository, who added it, and when.
Click Update.
Refresh the display by clicking Refresh Tree in the Resource Tree.
Tip:
To view the tracked changes to the content repository, you can create a log file of the repository content changes that are contained in the Behavior Tracking database tables, or you could enable listeners to provide specific logged output.You can disable the persistence of Behavior Tracking events by unregistering the Behavior Tracking listener or removing individual events.
This section contains the following topics:
Perform the following steps to unregister the Behavior Tracking listener:
Start the Administration Console.
In the Administration Console, choose Configuration & Monitoring > Service Administration.
In the Resource Tree, expand the Personalization folder and select Event Service.
In the Configure tab, locate the Behavior Tracking listener and select the Delete check box next to it.
Click Delete.
Refresh the display by clicking Refresh Tree in the Resource Tree.
Note:
Events could still be triggered to fire by the application, but they are not persisted to the database table.Perform the following steps to remove default events:
Start the Administration Console.
In the Administration Console, choose Configuration & Monitoring > Service Administration.
In the Resource Tree, expand the Personalization folder and select Behavior Tracking Service.
In the Configure tab, select the Delete check box for each event in the Persisted Event Types section that you want to remove, as shown in Figure 9-10.
Click Delete.
You must redeploy your application for the changes to take effect.