Skip Headers
Oracle Fusion Middleware Developer's Guide for Oracle WebCenter Analytics
10g Release 4 (10.3.0.2.0)
Part Number E14113-02
Go to Documentation Home
Home		 Go to Table of Contents
Contents		 Go to Feedback page
Contact Us
Go to previous page
Previous		 Go to next page
Next
View PDF

1 Oracle WebCenter Analytics OpenUsage API

The Oracle WebCenter Analytics OpenUsage API allows you to raise Oracle WebCenter Analytics events from custom portlets and applications and store them in the Oracle WebCenter Analytics database. This chapter presents an introduction to OpenUsage and provides basic use cases and a simplified example. The sample application includes examples of calling the OpenUsage Java API and using the OpenUsage event tag.

Oracle WebCenter Analytics collects information about the activity taking place within the Oracle WebCenter Interaction portal and in web applications, so you can respond better to your users' needs. Oracle WebCenter Analytics delivers detailed information about the use of specific content items and portlets, as well as community activity such as document downloads and discussion postings; it can even track activity by group or individual user. These usage details help ensure you develop and deliver the best content and applications for your users.

The only requirement for using the OpenUsage API is to have the OpenUsage libraries and a connection to a network that allows UDP traffic. The OpenUsage API sends portal usage tracking metrics from the Oracle WebCenter Interaction component on the portal server, as well as custom portal and non-portal events from external applications, to the Oracle WebCenter Analytics Collector Service via the Portal Message Bus (PMB). Oracle WebCenter Analytics services are installed on a stand-alone Oracle WebCenter Analytics Services Server. The Oracle WebCenter Analytics database stores all the metrics gathered and returns them to the Oracle WebCenter Analytics Services Server or external application. The Oracle WebCenter Analytics Service provides data to end users through the Oracle WebCenter Analytics Console or portlets on the portal server.

For details on installing and configuring Oracle WebCenter Analytics components, see the Oracle Fusion Middleware Oracle WebCenter Analytics Installation and Upgrade Guide for Oracle WebLogic Portal or Oracle Fusion Middleware Oracle WebCenter Analytics Installation and Upgrade Guide for Oracle WebCenter Interaction. The Oracle WebCenter Analytics Administration utility in the Oracle WebCenter Interaction portal provides a simple interface for defining custom events, parameters, and dimensions. Event data can then be queried using SQL for reporting to a non-portal application.

To get started with Oracle WebCenter Analytics and the OpenUsage API, see the necessary steps in the following sections:

Additional Resources

The following resources can be found on the Oracle Technology Network at http://www.oracle.com/technology/index.html.

Defining An Event Model

The first step to using Oracle WebCenter Analytics functionality in a custom application is deciding which events are useful and what information you want to track. The Oracle WebCenter Analytics database uses a standard star schema, providing almost unlimited flexibility in data storage.

Follow the steps below to define your event model:

  1. Identify the events you want to capture. An event typically defines one user action, for example, clicks, page visits, or downloads. In many cases, you can use portal events to capture the information you need. The OpenUsage API provides access to the following standard portal events:

    • Directory views

    • Document views

    • Page views

    • Portlet views and use

    • Search query and results

    • Login/logoff

    You can also raise custom events and define your own parameters. A new fact table is created in the Oracle WebCenter Analytics database for every custom event. For details on the Oracle WebCenter Analytics database implementation, see the Oracle WebCenter Analytics Database Schema.

  2. Identify facts about the event you want to track, for example, date, time, page, user, group, or member status. Each event includes several facts, represented by event parameters, which define the types of data generated by the event. By default, every event includes the following event parameters:

    Parameter ID Parameter Description

    USERID

    The ID of the user who triggers the event. You must use the OpenUsage API to set the User ID.

    TIMEID

    The unique ID number that is created for each occurrence of the event. This value is set by Oracle WebCenter Analytics.

    VISITID

    The portal visit ID of the user who triggered the event. This parameter is only compatible with events that occur in the portal. This value is set by Oracle WebCenter Analytics.

    OCCURRED

    The date and time when the event was generated. The format of the date/time stamp is determined by your database type. This value is set by Oracle WebCenter Analytics.

    All the interfaces in the OpenUsage API include methods to get and set standard parameters, including user ID, portlet ID, page ID, URL, and referer. For a complete list of the standard parameters for each event type, see the OpenUsage API documentation (javadoc). You can also create your own event parameters to capture data that is not defined by the delivered defaults.

  3. To capture non-numeric data, define a dimension table, for example, URL, page name, user name, group name, or membership level. You can use dimensions from your own application's tables or create new ones in Oracle WebCenter Analytics Administration (see Registering and Configuring Events in Oracle WebCenter Analytics Administration).

Event Model Examples

The following examples describe event models.

User interest statistics

Palo Alto Golf Course (PAGC) is setting up new classes and wants to see which topics users are most interested in. They decide to post a portlet listing three problem-specific articles on Golf Digest's web site and track which of the links users click on the most. They also want to track users' skill levels since it is defined as a user property in their portal. Since the users are divided among three portal groups, PAGC also wants to track the users' group membership.

Solution: PAGC creates a portlet that displays links to the three articles. Each link points to a redirect page that calls the sendEvent method in the OpenUsage API, passing the event type ID for that page, the date-time, and user ID. The redirect page redirects to the actual link target. An administrator registers a custom event for the article click in Oracle WebCenter Analytics Administration, along with the corresponding event parameters (event type ID, date-time, and user ID). The user ID parameter corresponds to the existing portal user dimension table, which includes skill level and group membership. PAGC creates a report that displays which links were clicked most often, grouped by skill level or portal group.

Customer follow-through statistics

BMW is working on a portal application for ordering car accessories online. The application allows users to browse a catalog of items, view details, add the items to a shopping cart, and purchase the items added to the cart. BMW would like to track the following statistics:

  • Number of times a user clicked to browse the catalog

  • Number of times (by item) a user selected to see each item's detailed description

  • Number of shopping cart sessions initiated

  • Number of times (by item) each item was added to a shopping cart

  • Number of times (by item) each item was converted into an order

Solution: All events can be captured by calling the OpenUsage API from the portal application. The VIEW_ITEM event could also be captured by placing an OpenUsage event tag on the details page. An administrator registers the five custom events in Oracle WebCenter Analytics Administration:

BROWSE

Sent when a user clicks the catalog browse button.

VIEW_ITEM

Sent when a user views the details of a particular item. Item ID is passed as a parameter.

NEW_SHOPPING_CART

Sent when a new shopping cart session is initialized.

ADD_ITEM

Sent when a user adds an item to a shopping cart. Item ID is passed as a parameter.

CONVERTED_ITEM

Sent when an item is converted into an order. Item ID is passed as a parameter.

BMW creates reports to display how many users clicked to browse the catalog, to display how many initiated shopping cart sessions, and to show details on how many times each item was viewed, added to a cart, and/or purchased.

Content repository usage statistics

Netformx Software has a knowledge base search portlet on its support page that allows users to search for a term in user manuals, articles, marketing material, and/or white papers. Netformx would like to know which of these four repositories is searched the most via the portlet.

Solution: The portlet calls the OpenUsageAPI when the Search button is clicked, passing in the appropriate knowledge repository as the event parameter. If more than one repository was selected, an event is sent for each selected repository. If the portlet uses either the ISearchEvent or the IDirView interface to raise a standard portal event, there is no need to register a custom event in Oracle WebCenter Analytics Administration. Netformx creates a report to compare usage of the four repositories.

Advertising campaign statistics

St. Paul Brewing Company is rolling out a new beer that has no carbs, no calories, and no taste. They plan on promoting the beer via e-mail and advertisements on Google and Yahoo. They would like statistics for the following:

  • Number of emails read

  • Number of click-throughs from each campaign (that is, email, Google, Yahoo)

  • Number of new user accounts created due to click-throughs from campaigns, per campaign

  • Number of community visits to the new beer community generated from each marketing campaign

  • Number of free beer coupons (document in KD) downloaded due to each marketing campaign

Solution: As with the other examples, all events can be sent via an OpenUsage API call with appropriate parameters. Page visits can be tracked using OpenUsage tags. An administrator registers any custom events and custom event parameters in Oracle WebCenter Analytics Administration. A range of reports can be created to display statistics from the campaign.

The next step is to register any custom events in Oracle WebCenter Analytics Administration. For details, see Registering and Configuring Events in Oracle WebCenter Analytics Administration.

Registering and Configuring Events in Oracle WebCenter Analytics Administration

You must register any custom events in Oracle WebCenter Analytics Administration so they will be recognized by the Oracle WebCenter Analytics Collector Service. Portal events are collected automatically. Custom (non-portal) events are called Managed Events in Oracle WebCenter Analytics Administration.

To capture non-numeric data, you must use a dimension table. You can use existing dimension tables or create new ones, called Managed Dimensions in Oracle WebCenter Analytics Administration. After you create a new dimension, you must create a new event parameter of type String, and associate it to the dimension (see Steps 3 to 5 below). To use an existing dimension table, create a parameter of type Integer that maps to the ID column in your dimension table. It is recommended that you do not create too many new dimensions, since they slow down the speed of data collection and reporting. The sample application used in this example displays links in a portlet and tracks which pages are accessed by users. The application also keeps track of which OpenUsage method is used to raise the event. The event model uses one custom event with four parameters, two of which have associated dimension tables. These instructions explain how to register this custom event in Oracle WebCenter Analytics Administration:

  1. Go to Oracle WebCenter Interaction portal Administration. Click the Select Utility drop-down list, and select Analytics Administration.

  2. Go to the Event Registration page in Analytics Manager.

  3. Under Managed Dimensions, click Add. Create a new dimension called event method. (Dimension names can be up to 20 characters in length and can only include letters, numbers, spaces, and underscores.) Leave the default table name. If you are expecting a small number of unique values for a dimension, select the Unique? checkbox to reduce the size of the table.

  4. Under Managed Dimensions, click Add. Create a new dimension called page name. Leave the default table name.

  5. Under Managed Events, click Add. Create a new event called demo event with the parameters listed in the table below.

    Note:

    Leave the default table name and column names. (Event and parameter names can be up to 14 characters in length and can only include letters, numbers, spaces, and underscores.) Make sure to use unique names that are not reserved words in the associated database.

    Name Data Type Dimension

    page id

    Integer

    —

    page name

    String

    page name

    event method

    String

    event method

    event date

    Date

    —

  6. Click Finish to save the event.

  7. On the Event Registration page, select the check box next to the new “demo event” you created in step 5 and click Enable. (By default, the Oracle WebCenter Analytics Collector Service starts saving an event's data 30 minutes after you click Enable.)

  8. Click Finish to save your changes.

WARNING:

You cannot remove or rename an event or its parameters and dimensions after clicking Finish on the Event Registration page.

Note:

The Event Registration page lists the names of the tables created in the Oracle WebCenter Analytics database for the custom event and its dimensions (ASCFACT_* for fact tables and ASCDIM_* for dimension tables). These table names are used to query the database only. The OpenUsage API uses the event or dimension name as defined in the UI (that is, "demo event" not "ASCFACT_DEMO_EVENT"). For details on the other pages in Oracle WebCenter Analytics Administration, see the online help or the Administrator Guide. The next step is to add events to your custom application.

Raising Oracle WebCenter Analytics Events from a Custom Application

After you have defined your events in Oracle WebCenter Analytics Administration, you can use OpenUsage to raise events in response to user actions.

This example is a sample application implemented as a portlet. The portlet is a JSP page that displays two static links and a text box with a submit button ("Go to My Demo Page!"). At the bottom of the portlet, there are two radio buttons and another submit button ("View Events!"). Each link in the portlet uses a different approach to raise an event.

Using the OpenUsage Event Tag

The first link ("OpenUsage Rocks") takes the user to another JSP page that raises an event using the <pt:as.event> tag. As shown in the code snippet below, the tag is implemented by including it in the page. Include a pt:as.fact attribute for each parameter defined for the event in Oracle WebCenter Analytics Administration.

For additional details on syntax, see the OpenUsage TagDocs.

Note:

Tags can be used only in portlets and gatewayed pages because they must be processed by the Oracle WebCenter Interaction Tag Transformation Engine. For more information on using tags, Oracle WebCenter Interaction Web Service Development Guide.

<p><html>
<body>
...

<h1>OpenUsage Rocks!</h1>
<p>(This page generates an event using the OpenUsage Portal Tag Library)
<p><a href="demo.jsp">Back</a>

<!-- Send the event using the OpenUsage tag library -->
<span xmlns:pt='http://www.plumtree.com/xmlschemas/ptui/'>
<pt:as.event pt:name="demo event" pt:userID="1">
  <pt:as.fact pt:name="page id" pt:value="1" pt:type="integer"/>
  <pt:as.fact pt:name="page name" pt:value="OpenUsage Rocks!" pt:type="string"/>
  <pt:as.fact pt:name="event method" pt:value="OpenUsage Tag Library" pt:type="string"/>
  <pt:as.fact pt:name="date" pt:value="<%= currentDateString%>" pt:type="date"/>
</pt:as.event>
</span>
</body>
</html>

Using the OpenUsage Java API

The second link in the portlet takes the user to another JSP page that raises an event using the OpenUsage API. First, a new event is created using the ASEventFactory.createManagedEvent() method. A setParameter() method is called for each parameter defined for the event in Oracle WebCenter Analytics Administration. Finally, the event is raised and sent to Oracle WebCenter Analytics using the sendEvent() method. These methods can be used in any application that has access to the OpenUsage libraries and connection to a network that allows UDP traffic. For additional details on these methods, see the OpenUsage API documentation (javadoc).

<p><%@page import="java.text.SimpleDateFormat"%>
<%@page import="com.plumtree.analytics.openusage.*"%></p><p><html>
<body>

<h1>OpenUsage Is A-OK!</h1>
<p>
  (This page generates an event using the OpenUsage Java API)
<p>

<a href="demo.jsp">Back</a

<%
  // create the event using the OpenUsage Java API
  ASEventFactory.setConfig(...);
  IManagedEvent evt = ASEventFactory.createManagedEvent("demo event");
  evt.setParameter("page id", new Integer(3));
  evt.setParameter("page name", "OpenUsage Is A-OK!");
  evt.setParameter("event method", "OpenUsage Java API");
  evt.setLongAsDateParameter("date", new Long(System.currentTimeMillis()));</p><p> // send it!
  evt.sendEvent(); 
%>

</body>
</html>

You could also use a text box/submit button in the portlet and use the OpenUsage API to raise an event. The form would include a hidden input element that triggers a Java servlet to raise the event. The code used by the servlet to raise the event would be identical to the code above except it would take in the page name entered in the text box and store this value in the page name dimension table. The next step is to configure Oracle WebCenter Analytics to store events from your custom application.

Configuring and Launching Oracle WebCenter Analytics

You must configure Oracle WebCenter Analytics to store events from custom applications by modifying the database.properties and openusage.xml files.

The instructions below are simplified for example purposes only. For a list of ports used by Oracle WebCenter Analytics and details on configuring the Oracle WebCenter Analytics database, see the Oracle Fusion Middleware Oracle WebCenter Analytics Installation and Upgrade Guide for Oracle WebLogic Portal or Oracle Fusion Middleware Oracle WebCenter Analytics Installation and Upgrade Guide for Oracle WebCenter Interaction.

  1. Open the openusage.xml file and enter the Oracle WebCenter Analytics server port:

    <UNICAST_MODE>YES</UNICAST_MODE>
<UNICAST_IP>$analytics_server_host$|port=31314</UNICAST_IP>

  2. Open the database.properties file and enter database information for the Oracle WebCenter Analytics Server. (Use the appropriate driver and URL for your configuration.)

    jdbc.driver=com.plumtree.jdbc.sqlserver.SQLServerDriver
jdbc.url=jdbc\:plumtree\:sqlserver\://$analytics_database_server$\:1433;DatabaseName\=$analytics_database_name$
jdbc.user=$analytics_database_user$
jdbc.password=$analytics_database_password$

  3. Place both configuration files in the appropriate config location. You can place the openusage.xml file anywhere, but your code must reference this file when initializing OpenUsage. This is done by calling the following method, where configDirectory is the path to the folder where openusage.xml is located. (This method only needs to be called once during your application run, normally during startup).

    ASEventFactory.setConfig("configDirectory", "openusage.xml");

    In the sample application, the OpenUsageDemoServlet class calls setConfig in the init() method. The configDirectory parameter is defined in web.xml as .\openusage-demo\config\settings. To change this location, open the .war file and modify the configDirectory init-param in web.xml.

  4. Deploy the application .war file to any Java Servlet Container.

  5. On the Oracle WebCenter Analytics server, make sure the Analytics Collector Service is started.

To view the events from your custom application, query the Oracle WebCenter Analytics database. For details, see Querying Oracle WebCenter Analytics and Displaying Statistics.

Querying Oracle WebCenter Analytics and Displaying Statistics

To retrieve data from the Oracle WebCenter Analytics database for custom reports, use SQL.

To define or determine table and column names, go to the Event Registration page of Oracle WebCenter Analytics Administration (see Defining An Event Model). For descriptions of the tables that are delivered with Oracle WebCenter Analytics, see the Oracle WebCenter Analytics Database Schema. In this sample application, the "View Events!" button opens a JSP page with a pie chart that shows the percentage of clicks by page name or event method. The query to the Oracle WebCenter Analytics database is handled in the same servlet that raises the Go to My Demo Page! event. The sample application uses a JFreeCharts dataset producer to iterate over the data. The JSP page that displays the pie charts uses cewolf tags to render the data from the JFreeCharts dataset producer.

/**
* View "demo event" data using JFreeCharts and cewolf tag libraries.
*
* @param req HttpServletRequest
* @param res HttpServletResponse
*/

public void viewEvents(HttpServletRequest req, HttpServletResponse res) 
throws IOException, ServletException {
try {
    Connection conn = getDatabaseConnection();
    Statement stmt = conn.createStatement();
    String query = "";

        if ("EVENT_METHOD".equals(req.getParameter("groupby"))) {
            // group by eventMethod
        query = "select count(*), method.value " + "from ascfact_demo_event fact, ascdim_page_name page, ascdim_event_method method " + "where fact.page_name = page.id and fact.event_method = method.id " + "group by method.value";
        req.getSession().setAttribute("GROUP_BY_CHECKED", "EVENT_METHOD"); 

        } else {
            // group by pageName
        query = "select count(*), page.value " + "from ascfact_demo_event fact, ascdim_page_name page, ascdim_event_method method " + "where fact.page_name = page.id and fact.event_method = method.id " + "group by page.value";
        req.getSession().setAttribute("GROUP_BY_CHECKED", "PAGE_NAME"); 
    }

    // execute the query
    ResultSet results = stmt.executeQuery(query);

    // create a JFreeChart DatasetProducer which will be rendered by the cewolf tag library
    DatasetProducer datasource = new PieChartDatasetProducer(results);
    req.setAttribute("datasource", datasource);

    // close database resources
    results.close();
    stmt.close();
    conn.close();

} catch (Exception e) {
e.printStackTrace();
throw new ServletException("Exception while creating DatasetProducer - " + e);
}

RequestDispatcher dis = req.getRequestDispatcher("demo_chart.jsp"); 
dis.forward(req, res);
}</p>

(Oracle WebCenter Analytics includes a collection of standard reports that display portal events; for details, see the Administrator Guide for Oracle WebCenter Analytics.) For more information on querying the Oracle WebCenter Analytics database from custom applications, see the next section, Chapter 2, "Oracle WebCenter Analytics Query API."

Go to previous page
Previous		 Go to next page
Next
Go to Documentation Home
Home		 Go to Table of Contents
Contents		 Go to Feedback page
Contact Us