46 Integrating the Analytics Service

The Analytics service enables you to display usage and performance metrics for WebCenter Portal applications. This chapter describes how to integrate the Analytics service into WebCenter Portal applications.

46.1 Introduction to the Analytics Service

The Analytics service offers real-time usage and activity reporting for your portal. This section provides an overview of the Analytics service, its task flows, and its usages. It includes the following subsections:

46.1.1 Understanding the Analytics Service

The Analytics service allows administrators and users to track and analyze traffic and usage in WebCenter Portal applications. The Analytics service provides the following basic functionality:

Usage Tracking Metrics: The Analytics service collects and reports metrics for common portal functions, including community, page, portlet, and document hits.

Behavior Tracking: The Analytics service can be used to analyze WebCenter Spaces metrics to determine usage patterns, such as Space visit duration and usage over time.

User Profile Correlation: The Analytics service can be used to correlate metric information with user profile information. Usage tracking reports can be viewed and filtered by user profile data such as country, company or title.

Displays the number of page hits and the number of unique users that visited any page within the portal.

Login Metrics

Reports portal logins.

Portlet Traffic

Displays usage data for a portlet.

Portlet Response Time

Displays performance data for a portlet.

Portlet Instance Traffic

Displays usage data for a portlet instance*.

Portlet Instance Response Time

Displays performance data for a portlet instance*.

Search Metrics

Tracks portal searches.

Document Metrics

Tracks document views.

Wiki Metrics

Tracks most popular/least popular wikis.

Blog Metrics

Tracks most popular/least popular blogs.

Discussion Metrics

Tracks most popular/least popular discussions.

* If the same portlet is displayed on several different pages, each placement is known as a portlet instance.

46.1.2 Requirements for the Analytics Service

The Analytics service requires that the analytics schema (ACTIVITIES) is installed and up and running. In addition, the Oracle WebCenter Analytics Collector must be up and running on the WC_Utilities managed server. For detailed installation instructions, see Oracle Fusion Middleware Installation Guide for Oracle WebCenter.

46.1.3 What Happens at Runtime

At runtime, user activity in your WebCenter Portal application generates event data. For example, every time a user logins in, reads a discussion topic, views a document, and so on, the event is recorded. The OpenUsage API sends event metrics to the Analytics Collector using UDP (User Datagram Protocol) and the event data is stored in the analytics database (ACTIVITIES).

In a non clustered environment the WebCenter Portal application is configured with the location of the collector, and all events are transmitted to that location.

In a clustered environment both the WebCenter Portal application and Analytics Collector are configured with a cluster-specific channel name. Each collector periodically broadcasts a heartbeat with its location to the cluster-specific channel. The WebCenter Portal application listens to the channel for these collector heartbeats, and when it hears one, adds the collector to its list of known collectors. When the WebCenter Portal application sends an event it randomly selects a collector from its list and sends the event to that collector. If a collector stops (either being stopped purposefully or failing) it stops broadcasting a heartbeat. When the WebCenter Portal application stops hearing the heartbeat it removes the collector from its list and stops sending events to that collector. If the WebCenter Portal application does not hear any collector heartbeats it does not send any events.

6. Test that analytics data is available in the WebCenter Portal application

6.a Log in to the WebCenter Portal application

6.b Display the analytics task flow

46.2.2 Setting up Connections for the Analytics Service

The Analytics service requires that the WebCenter Portal application is connected to the analytics database (ACTIVITIES). You must also configure the WebCenter Portal application to send event information to a specific Analytics Collector.

Note:

While you can set up the connections to back-end servers at design time in JDeveloper, you can later add, delete, or modify connections in your deployed environment using Enterprise Manager Fusion Middleware Control. For more information, see "Managing the Analytics Service" in Oracle Fusion Middleware Administrator's Guide for Oracle WebCenter.

oracle.wc.openusage.unicast - Specifies whether events are sent to a clustered Analytics Collector in multicast mode or whether a single Analytics Collector using unicast communication is required. Valid values are true and false. The default value is true (unicast).

oracle.wc.openusage.clustername - Name of the collector cluster or the host name of an Analytics Collector (if unicast is enabled). The default value is localhost.

oracle.wc.openusage.collectorport - Port on which the Analytics Collector listens for events. The default value is 31314.

oracle.wc.openusage.timeout Period of time (in seconds) used to determine availability of the collector service in multicast mode. The default value is 30 seconds.

To set Analytics Collector JVM properties:

In JDeveloper, choose Run, Active Run Configuration, and then Manage Run Configurations from the main menu.

In the Project Properties dialog, select the Default run configuration, and then click Edit.

In the Launch Settings section, add the following OpenUsage options to the Java Options field as follows:

46.2.3 Configuring a Namespace for Analytics Customizations in MDS

Analytics task flows use MDS to store customizations made by the user and these customizations are stored in an MDS namespace specific to analytics. If you want to enable user customizations for analytics task flows in your WebCenter Portal application, you must configure a namespace for the analytics metadata in adf-config.xml.

The task flow is added to the page, and the ViewController project's libraries are configured to run the task flow.

Save your project and run the page to see the task flow running in the WebCenter Portal application.

If no usage data exists when you run the application, analytics task flows display the message: No data to display

You may create some data for the analytics task flow to display by performing actions that relate to the task flow you are testing. For example, to test discussion metrics, create and view discussions, to test page metrics, create and view pages, and so on.

46.2.4.3 How to Modify Analytics Task Flow Parameters

Each analytics task flow has a set of required and optional task flow binding parameters. Required parameters are not mandatory but enable you to capture information that is essential to the task flow's successful function. For example, if you want user customizations for a particular task flow instance to be stored in MDS you must specify the MDS document required.

In addition, you can use task flow binding parameters to customize the appearance and behavior of a task flow instance. For example, you can use parameter values to specify a display title above your analytics data.

You can also adjust task flow binding parameter values after you have placed a task flow on a page at run time. For details, see "Setting Analytics Task Flow Properties" in the Oracle Fusion Middleware User's Guide for Oracle WebCenter Spaces.

To access the Edit Task Flow Binding dialog:

Click the Bindings tab at the bottom of the page (next to the Source tab) to go to the Bindings view.

Under Executables, you will see a list of task flows added to the page. Select the analytics task flow (Figure 46-5).

Figure 46-5 Accessing Input Parameters for Analytics Task Flows

Next to the Executables heading, click the Edit selected element icon (a pencil).

When you are finished, save the page and run your page to see the results.

46.2.4.4 How to Allow End Users to Customize Analytics Task Flows at Runtime

If you want to enable user customizations for a particular task flow instance you must specify the MDS document where customizations are stored using the Analytics Resource Id parameter.

The ID must be unique, so consider using a consistent naming pattern such as <app_name>_<page_name>_<task_flow>_<sequence>. For example, set the analyticsResourceId parameter for a Page Traffic task flow to myapp_analyticspage_pagetraffic_1.

46.2.5 Setting up Security for Analytics Task Flows and Usage Data

Analytics task flows are intended to make usage metrics visible to a limited set of administrative users who perform particular business functions, such as capacity planning, quality of service (QoS) analysis, return on investment (ROI) analysis, "best bet" customization for Search, and so on.

Analytics usage data is valuable for portal analysis but might be regarded as private or sensitive to portal users. For example, the Search, Document, and Portlet reports can be configured to display activity metrics for a particular user, based on user properties such as E-mail Address, First Name, or Last Name.

To ensure that only a limited number of administrative users can add analytics task flows to pages, create reports based on custom analytics data controls, or view pages set up to display sensitive usage metrics, create a new administrative group and manage group membership accordingly.

Manage user access to analytics task flows.

Ensure analytics task flows and custom reports do not contain private or sensitive data unless such a view is particularly intended. If the metrics in the report do contain private or sensitive data, configure security so that only appropriate, specified users have access to the task flow or the page.

For example, at design-time, developers can expose the analytics task flows to non-admin users by granting them appropriate privileges to the page. In addition, developers can customize the reports pre-deployment, to hide or show and predefine certain report options (such as time frame, chart type, user property filter, group by option, and so on). Administrators will be able to perform the same tasks at runtime, that is, grant page access and customize the information that displays. Non-admin users can still personalize the reports they are allowed to see, but they cannot change customizations made by the administrator.

Ensure that unauthenticated users are never allowed to add analytics task flows to pages or see sensitive data.

46.3 Building Analytics Reports

Out-of-the-box analytics task flows present common analytics event metrics in a specific display format. If you want to present analytics data in a different way or display custom event data, you can build a custom analytics report using SQL.

46.3.1 Using SQL Data Controls

Use SQL data controls to define, in an SQL query statement, the information you want to retrieve from the analytics database. When you expose data controls on a page you can choose whether the analytics data presents in a graph, table or a form, and you can also configure the bind parameters and other display options.

Use a SQL data control to fetch data from the analytics database and display analytics data in your WebCenter application. Figure 46-9 shows the sample SQL statement below in an the Create/Edit SQL Data Control dialog in WebCenter Spaces. A database connection to the analytics database (ActivitiesDS) is required, and you must provide a valid database password.

Sample SQL: Page Hits by Day

SELECT space.name_, page.name_, space.id, page.id, count(1), fact.page_, page.resourceid_
FROM asfact_wc_pagevie_0 fact, asdim_wc_groupsp_0 space, asdim_wc_pages_0 page, asdim_wc_applica_0 app
WHERE space.id = fact.groupspace_
and page.id = fact.page_
and app.id = fact.application_
and fact.occurred between to_date(:startdate, :dateformat)
and to_date(:enddate, :dateformat)
and app.name_ = :appname
and page.personal_ = :ispersonal
and space.name_ is not null
and page.name_ is not null
and space.id is not null
and page.id is not null
and fact.page_ is not null
and page.resourceid_ is not null
GROUP BY space.name_, page.name_, space.id, page.id, fact.page_, page.resourceid_
ORDER BY count(1) desc

Figure 46-9 Creating SQL Data Control Dialog in WebCenter Spaces

You can add as many bind parameters as required. When you add parameters, you can restrict the data retrieved from the data source based on the parameter values you specify. As this example is for WebCenter Spaces, the name of the application is set to webcenter and personal pages (pages in the Home Space) are included in the report shown in Figure 46-10.

Figure 46-10 Setting Report Parameters

Table 46-5 Report Parameters

Parameter

Default Value

Description

appname

webcenter

The corresponding application name, always webcenter for WebCenter Spaces. Other WebCenter Portal applications will have a different name.

ispersonal

0 or 1

For WebCenter Spaces, determines whether or not pages created in the Home Spaces are included in the report.

dateformat

mm/dd/yyyy hh24

Any valid pattern for dates in an Oracle database. Every component of the pattern is optional since it depends on the data you want to retrieve.

46.3.2.2 Analytics SQL: Page Traffic

SELECT space.name_, page.name_, space.id, page.id, count(1), fact.page_, page.resourceid_
FROM asfact_wc_pagevie_0 fact, asdim_wc_groupsp_0 space, asdim_wc_pages_0 page, asdim_wc_applica_0 app
WHERE space.id = fact.groupspace_
and page.id = fact.page_
and app.id = fact.application_
and fact.occurred between to_date(:startdate, :dateformat)
and to_date(:enddate, :dateformat)
and app.name_ = :appname
and page.personal_ = :ispersonal
and space.name_ is not null
and page.name_ is not null
and space.id is not null
and page.id is not null
and fact.page_ is not null
and page.resourceid_ is not null
GROUP BY space.name_, page.name_, space.id, page.id, fact.page_, page.resourceid_
ORDER BY count(1) desc

46.3.2.4 Analytics SQL: Space Traffic

SELECT space.name_, space.id, count(1), fact.groupspace_, space.resourceid_
FROM asfact_wc_groupsp_0 fact, asdim_wc_groupsp_0 space, asdim_wc_applica_0 app
WHERE space.id = fact.groupspace_
and app.id = fact.application_
and fact.occurred between to_date(:startdate, :dateformat)
and to_date(:enddate, :dateformat)
and app.name_ = :appname
and space.personal_ = :ispersonal
and space.name_ is not null
and space.id is not null
and fact.groupspace_ is not null
and space.resourceid_ is not null
GROUP BY space.name_, space.id, fact.groupspace_, space.resourceid_
ORDER BY count(1) desc

46.3.2.5 Analytics SQL: Space Response Time

SELECT space.name_, space.id, avg(fact.response_time_), fact.groupspace_, space.resourceid_
FROM asfact_wc_groupsp_0 fact, asdim_wc_groupsp_0 space, asdim_wc_applica_0 app
WHERE space.id = fact.groupspace_
and app.id = fact.application_
and fact.occurred between to_date(:startdate, :dateformat)
and to_date(:enddate, :dateformat)
and app.name_ = :appname
and space.personal_ = :ispersonal
and space.name_ is not null
and space.id is not null
and fact.groupspace_ is not null
and space.resourceid_ is not null
GROUP BY space.name_, space.id, fact.groupspace_, space.resourceid_

46.3.2.6 Analytics SQL: Portlet Traffic

SELECT portlet.default_title_, portlet.id, count(1), fact.portlet_, portlet.resourceid_
FROM asfact_wc_portlet_0 fact, asdim_wc_portlet_0 portlet, asdim_wc_applica_0 app
WHERE app.id = fact.application_
and portlet.id = fact.portlet_
and fact.occurred between to_date(:startdate, :dateformat)
and to_date(:enddate, :dateformat)
and app.name_ = :appname
and portlet.default_title_ is not null
and portlet.id is not null
and fact.portlet_ is not null
and portlet.resourceid_ is not null
GROUP BY portlet.default_title_, portlet.id, fact.portlet_, portlet.resourceid_

46.3.2.7 Analytics SQL: Portlet Instance Traffic

SELECT space.name_, space.id, page.name_, page.id, portletinst.title_, portletinst.id, count(1), fact.portlet_instance_, portletinst.resourceid_
FROM asfact_wc_portlet_0 fact, asdim_wc_groupsp_0 space, asdim_wc_pages_0 page, asdim_wc_portlet_1 portletinst, asdim_wc_applica_0 app
WHERE space.id = fact.groupspace_
and page.id = fact.page_
and app.id = fact.application_
and portletinst.id = fact.portlet_instance_
and fact.occurred between to_date(:startdate, :dateformat)
and to_date(:enddate, :dateformat)
and app.name_ = :appname
and space.name_ is not null
and space.id is not null
and page.name_ is not null
and page.id is not null
and portletinst.title_ is not null
and portletinst.id is not null
and fact.portlet_instance_ is not null
and portletinst.resourceid_ is not null
GROUP BY space.name_, space.id, page.name_, page.id, portletinst.title_, portletinst.id, fact.portlet_instance_, portletinst.resourceid_

46.3.2.8 Analytics SQL: Portlet Response Time

SELECT portlet.default_title_, portlet.id, avg(fact.response_time_), fact.portlet_, portlet.resourceid_
FROM asfact_wc_portlet_0 fact, asdim_wc_portlet_0 portlet, asdim_wc_applica_0 app
WHERE app.id = fact.application_
and portlet.id = fact.portlet_
and fact.occurred between to_date(:startdate, :dateformat)
and to_date(:enddate, :dateformat)
and app.name_ = :appname
and portlet.default_title_ is not null
and portlet.id is not null
and fact.portlet_ is not null
and portlet.resourceid_ is not null
GROUP BY portlet.default_title_, portlet.id, fact.portlet_, portlet.resourceid_

46.3.2.9 Analytics SQL: Portlet Instance Response Time

SELECT space.name_, space.id, page.name_, page.id, portletinst.title_, portletinst.id, avg(fact.response_time_), fact.portlet_instance_, portletinst.resourceid_
FROM asfact_wc_portlet_0 fact, asdim_wc_groupsp_0 space, asdim_wc_pages_0 page, asdim_wc_portlet_1 portletinst, asdim_wc_applica_0 app
WHERE space.id = fact.groupspace_
and page.id = fact.page_
and app.id = fact.application_
and portletinst.id = fact.portlet_instance_
and fact.occurred between to_date(:startdate, :dateformat)
and to_date(:enddate, :dateformat)
and app.name_ = :appname
and space.name_ is not null
and space.id is not null
and page.name_ is not null
and page.id is not null
and portletinst.title_ is not null
and portletinst.id is not null
and fact.portlet_instance_ is not null
and portletinst.resourceid_ is not null
GROUP BY space.name_, space.id, page.name_, page.id, portletinst.title_, portletinst.id, fact.portlet_instance_, portletinst.resourceid_

46.3.2.10 Analytics SQL: Search Metrics

SELECT search.phrase_, search.id, count(1)
FROM asfact_wc_searche_0 fact, asdim_wc_applica_0 app, asdim_wc_searche_0 search
WHERE app.id = fact.application_
and search.id = fact.searched_phrase_
and fact.occurred between to_date(:startdate, :dateformat)
and to_date(:enddate, :dateformat)
and app.name_ = :appname
and search.phrase_ is not null
and search.id is not null
GROUP BY search.phrase_, search.id

46.3.2.11 Analytics SQL: Document Metrics

SELECT doc.name_, doc.id, count(1), fact.document_, doc.resourceid_
FROM asfact_wc_doclib__0 fact, asdim_wc_documen_0 doc, asdim_wc_applica_0 app
WHERE app.id = fact.application_
and fact.document_ = doc.id
and fact.occurred between to_date(:startdate, :dateformat)
and to_date(:enddate, :dateformat)
and app.name_ = :appname
and doc.objecttype_ like '%DOCUMENT%'
and doc.name_ is not null
and doc.id is not null
and fact.document_ is not null
and doc.resourceid_ is not null
GROUP BY doc.name_, doc.id, fact.document_, doc.resourceid

46.3.2.12 Analytics SQL: Wiki Metrics

SELECT doc.name_, doc.id, count(1), fact.document_, doc.resourceid_
FROM asfact_wc_doclib__0 fact, asdim_wc_documen_0 doc, asdim_wc_applica_0 app
WHERE app.id = fact.application_
and fact.document_ = doc.id
and fact.occurred between to_date(:startdate, :dateformat)
and to_date(:enddate, :dateformat)
and app.name_ = :appname
and doc.objecttype_ like '%WIKI%'
and doc.name_ is not null
and doc.id is not null
and fact.document_ is not null
and doc.resourceid_ is not null
GROUP BY doc.name_, doc.id, fact.document_, doc.resourceid_

46.3.2.13 Analytics SQL: Blog Metrics

SELECT doc.name_, doc.id, count(1), fact.document_, doc.resourceid_
FROM asfact_wc_doclib__0 fact, asdim_wc_documen_0 doc, asdim_wc_applica_0 app
WHERE app.id = fact.application_
and fact.document_ = doc.id
and fact.occurred between to_date(:startdate, :dateformat)
and to_date(:enddate, :dateformat)
and app.name_ = :appname
and doc.objecttype_ like '%BLOG%'
and doc.name_ is not null
and doc.id is not null
and fact.document_ is not null
and doc.resourceid_ is not null
GROUP BY doc.name_, doc.id, fact.document_, doc.resourceid_

46.3.2.14 Analytics SQL: Discussion Metrics

SELECT forum.name_, forum.id, count(1), fact.topic_, forum.resourceid_
FROM asfact_wc_discuss_0 fact, asdim_wc_discuss_0 forum, asdim_wc_applica_0 app
WHERE app.id = fact.application_
and forum.id = fact.topic_
and fact.occurred between to_date(:startdate, :dateformat)
and to_date(:enddate, :dateformat)
and app.name_ = :appname
and forum.name_ is not null
and forum.id is not null
and fact.topic_ is not null
and forum.resourceid_ is not null
GROUP BY forum.name_, forum.id, fact.topic_, forum.resourceid_

46.3.3 Sample Queries for User Metrics

This section provides example queries for user-specific metrics. It includes the following samples: