Feature Overview #

This feature is no longer valid. It was incorporated by the Audit module available under EE license. This document captures the Functional Specification Document (FSD) for the Liferay server User Behavior Tracking.

Technology Overview #

The User Behavioral Tracking(UBT) provides a way to track user activity on the portal. This will enable third party tools to analyze user behavior. For better understanding UBT subsystem can be considered to be comprised of three main features:

1. UBT Configuration : This feature is responsible for providing interfaces to configure UBT Logging and UBT Reporting features.
2. UBT Logging : This feature is responsible for logging UBT data dynamically as per the user actions on portal.
3. UBT Reporting : This feature is responsible for providing a set of sample reports generated based on the data collected by UBT Logging system.

The tracked user activity is logged into external storage systems so that third party tools can analyze use behavior with respect to the portal. The following diagram shows the overall architecture of the system depicting how 'UBT Logging' fits into it.

Competitive Analysis #

There are techniques that use application service providers like Google Analytics or OpenTracker. These providers usually trace user activities by placing a certain piece of content that is pointing to a service provider in the page that is delivered to the user. After rendering the page, the browser retrieves those content items from the service provider. The service provider analyzes its access logs and provides its customer with reports about what was requested and when. This technique is also referred to as a "Web beacon".

Pros: These provide useful analytics such as..

• Most visited page
• Keywords ( search words that leads to this page)
• Visitor activity such as time on site, depth of visit
• User network ( domains/locations from which users came from)
• No of downloads etc.

Cons:

• Does not capture portal specific data
• Both the statistics and the software application are hosted by the providers.
• The tracking code needs to be inserted into every page that needs to be tracked.

What's there in Liferay

Liferay includes built-in support for Google Analytics, allowing administrators to make use of Google's tool set for analyzing site traffic data. All of the pages in the community can be tracked.

The limitation is that you need add the Google Analytics ID for each community that is created.

Constraints #

Assumptions and Dependencies #

1. This feature will use Liferay Hooks.

Requirements #

Product Level Requirements #

1. UBT should be optional. Must provide options to completely disable UBT

Functional Requirements #

UBT configuration

1. There shall be a provision to turn UBT logging 'ON' or 'OFF'.
2. By default, UBT logging shall be set to 'OFF'.In this case no UBT events are captured
3. It may be possible to selectively switch 'ON' or 'OFF' any UBT event.(Refer to Event enable/disable section for more details).
4. It may be possible to selectively switch 'ON' or 'OFF' any UBT event for a portlet.
5. There shall be a provision to see which terms users are searching most in the portal.
6. It may be possible to change the extent of the data that is logged for every user click on the portal.(Refer to Event enable/disable section for more details)
7. There shall be a provision to turn 'OFF' User ID captured as part of the UBT data. (This is to conform to privacy requirements, if any)
8. By default, User ID shall be captured as part of UBT data.
9. It shall be possible to change the data store to a different one such a database. The default will be logging to the filesystem.
10. If the UBT data is going into database, there shall be a mechanism to map the UBT fields to existing table fields in database.
11. It shall be possible to change the logging format. The default will be W3C Extender Logging Format
12. It shall be possible to export the data in CSV format

UBT logging

User Behavior on portal is captured by way of events. UBT logging framework can be used to enable generation of UBT events. Among the predefined UBT events, certain events are generated on every user's click on the portal, while certain other are generated automatically. It is possible that more than one UBT event is generated for one click on desktop. This is done in order to capture all visible, business-oriented portal changes.

UBT events

Each identified event is captured along with predefined attributes which are relevant in the context. Predefined UBT events may be broadly categorized into following four:

1. User Session events: These events are generated when a user does login, logout, or when user session terminates.
2. Page events: These events are generated when a user creates, reads, updates or deletes a page.
3. Portlet Events: These events are generated when render, action, event or resource requests are made to any portlet.
4. Portal Resource events: These events are generated when portal resources like users, groups, organizations, communities, roles are created, read, updated or deleted.

User session events:

1. SESSION_START
1. This event shall be generated when any authenticated user starts a fresh session with portal..
2. Event shall be generated only once for anonymous or authentication less user, when session is created inside portal
2. SESSION_TERMINATE
1. This event shall be generated when a user's session is terminated.
2. Event shall be generated for both termination due to session time out and user logging out.

Page events:

1. PAGE_READ
1. This event shall be generated when any user clicks on a page
2. PAGE_CREATE
1. This event shall be generated when any user creates a page
3. PAGE_UPDATE
1. This event shall be generated when any user updates the page
4. PAGE_DELETE
1. This event shall be generated when any user deletes a page

Portlet events:

1. PORTLET_RENDER
1. Event shall be generated when Render Request is made on a portlet.
2. PORTLET_ACTION
1. Event shall be generated when Action Request is made on a portlet.
3. PORTLET_EVENT
1. Event shall be generated when Event Request is made on a portlet.
4. PORTLET_RESOURCE
1. Event shall be generated when Resource Request is made on a portlet.

Portal Resource events:

1. PORTAL_RESOURCE_CREATE
1. These events are generated when portal resources like users, groups, organizations, communities, roles are created.
2. PORTAL_RESOURCE_READ
1. These events are generated when portal resources like users, groups, organizations, communities, roles are read.
3. PORTAL_RESOURCE_UPDATE
1. These events are generated when portal resources like users, groups, organizations, communities, roles are updated .
4. PORTAL_RESOURCE_DELETE
1. These events are generated when portal resources like users, groups, organizations, communities, roles are deleted.

Event enable/disable

1. Each event shall have a level associated with it.
2. Level shall determine if the event is enabled or disabled.
3. Level shall also determine extent of detail that is captured as part of the event.
4. Level of each UBT event shall be defined in ubt.properties file.For example, for UBT event PORTLET_RENDER, level may be defined as follows in the configuration file: ubt.PORTLET_RENDER.level=<value>, where <value> is any valid value of level.
5. Following shall be the valid values of 'level' for any UBT event. Level value 'OFF' indicates that the corresponding event is disabled and any other valid value indicates event is enabled.

• OFF
• INFO
• FINE
• FINER
• FINEST

Level-wise event attributes

1. Each event shall have a predefined set of attributes.
2. Each attribute shall be associated with a predefined level.
3. Based on the level of a event set in the UBT configuration file, only attributes that belong to that level or any level greater than the events level, shall be available for capture and storage. Level comparison is done based on the associated integer value of each level.

Following table shows list of attributes against the level they are attached to.

(2.3) UBT Reporting

• Sample reports shall be provided.

UBT Samples Reports are set of reports derived from the UBT data stores. As name suggests, these reports are feature demonstration pieces. They can be used to showcase the data that are captured as part of UBT and the details that can be derived from these data.

• Sample reports based on the following statistics shall be generated

1. An individual's current subscriptions to portlets/communities
2. Number of portal logins per hour/day/week/month
3. Number of users subscribed to a portlet
4. Number of users interacting with a portlet
5. Portlet popularity according to the number of users interacting with it, displayed as percentage of total. Example: portlet x =10% of clicks, portlet y = 5% of clicks, etc.
6. Number of page requests per hour of day
7. Number of users per org/role/group/community
8. Tab/Community Popularity (how often each tab/Community is accessed) per hour of day
9. Number of total portal customizations (Layout or Content change) per day (per community/tab)
10. Number of total portlet customizations(portlet edit) per day

• Third party tools like AWStats can be used to analyze the logs

User Interface Requirements #

There shall be a UI for UBT configuration

Performance Requirements #

The performance should not degrade by more than 10%

Design #

The Java logging framework will be used for UBT.