Usage Pattern Tracking

This chapter includes information about usage pattern tracking (UPT) in Siebel Business Applications. It includes the following topics:

About Usage Pattern Tracking

Usage pattern tracking allows administrators to review details about when and how often users access the features in a Siebel application. To capture information about this user access, administrators set up a component job to run at a scheduled date and time or at time intervals that they specify. Administrators can configure usage pattern tracking to apply to only the user events that they designate. They can also configure usage pattern tracking to apply to events that are associated with client scripts, such as browser scripts and JavaScripts, and with server scripts.

After the component job for usage pattern tracking runs, administrators can view information about the user events and event details in the Usage Pattern Tracking view of the Administration - Application screen.

For example, administrators can implement usage pattern tracking to:

Monitor how often users use a Siebel application, an applet, or a business component so that they have reliable information to change application configuration and features and to simplify the user interface.
Monitor how users use a feature in a Siebel application to facilitate user training and to gather details about the actions that lead to error conditions.
Monitor feature usage after application upgrades or during development cycles to evaluate the usefulness of upgrades or new development and to optimize test cycles.

Usage pattern tracking is designed to minimize the impact on the performance of Siebel Business Applications. It is recommended that administrators consider the business requirements of their organizations, and monitor only the necessary events to minimize any adverse affect on performance.

Process of Setting Up Usage Pattern Tracking

To set up usage pattern tracking, perform the following tasks:

Setting System Preferences for Usage Pattern Tracking

Complete the procedure in this topic to set the system preferences for usage pattern tracking.

This task is a step in Process of Setting Up Usage Pattern Tracking.

To set system preferences for usage pattern tracking

Navigate to the Administration - Application screen, then the System Preferences view.

Set the system preferences in the following table.

System Preference Description

System Preference	Description
Enable UPT	Set this system preference to TRUE to implement usage pattern tracking.
UPT Max Record Count	Set this system preference to the number of records for usage pattern tracking that are kept in memory. When memory exceeds the number of records that you specify for this system preference, the records are moved to .csv files for users at the following location: `siebsrvr\upt\username`. Eventually, the UPT Process workflow moves the information in the .csv files to tables in the Siebel database. For more information about these tables, see Viewing Usage Patterns. Available memory and the anticipated level of user activity determine the appropriate value for this system preference. Its minimum value is 100, and its maximum value is 1,000.

Enable UPT

Set this system preference to TRUE to implement usage pattern tracking.

UPT Max Record Count

Set this system preference to the number of records for usage pattern tracking that are kept in memory. When memory exceeds the number of records that you specify for this system preference, the records are moved to .csv files for users at the following location: siebsrvr\upt\username. Eventually, the UPT Process workflow moves the information in the .csv files to tables in the Siebel database. For more information about these tables, see Viewing Usage Patterns. Available memory and the anticipated level of user activity determine the appropriate value for this system preference. Its minimum value is 100, and its maximum value is 1,000.

Complete the following steps to create system preferences for the end-to-end events (EEEs) to include in usage pattern tracking (UPT):
1. In the System Preference Name field, enter a name, such as UPTEEE1, UPTEEE2, for the pair of events in each end-to-end event.
2. In the System Preference Value field, enter a pair of events for each name in Step a, and separate the events with a comma.
  
  The first event designates the start of the end-to-end event, and the second event designates the end of the end-to-end event. Example event pairs include: WebLogin, WebLogout and ViewActivated, ViewDeactivated.
  
  You can obtain possible events by navigating to the Events view of the Administration - Runtime Events screen. Each value (Applet, Application, and BusComp) in the Object Type field of this view is associated with a set of events in the Events field of this view. Both of the events that you enter in an end-to-end event must be associated with the same object type. For information about the descriptions of event values, see Siebel Personalization Administration Guide.
3. In the System Preference Name field, enter a name of UPTEndToEndEventList.
4. In the System Preference Value field for the UPTEndToEndEventList name, enter each name that you create in Step a, and separate each name with a comma.
To implement the system preferences that you set, restart the Siebel Application Object Manager component.
For information about restarting Siebel Server components, see Siebel System Administration Guide.

Process of Configuring Usage Pattern Tracking

To configure usage pattern tracking, perform the following tasks:

Creating Action Sets for Events

An action set includes the actions that are executed when an event occurs. After you create an action set with one action for usage pattern tracking, you associate this action set with the events that you want to monitor. For more information about creating action sets, see Siebel Personalization Administration Guide.

This task is a step in Process of Configuring Usage Pattern Tracking.

To create an action set for events

Navigate to the Administration - Runtime Events screen, then the Action Sets view.

In the Action Sets list, create a new record, and complete the necessary fields.

Some of the fields are described in the following table.

Field	Comments
Name	Type a name for the action set.

In the Actions list, create a new record for the action in the action set, and complete the necessary fields.

Some of the fields are described in the following table.

Field	Comments
Name	Type a name for the action.
Action Type	Select the BusService action type for the action.
Sequence	Type a sequence number of 1 for the action.
Business Service Name	Type Usage Pattern Service for the business service of the action.
Business Service Method	Type UsageLog for the business service method of the action.

Associating Action Sets With Events

After creating the action set, you associate it with the events to include in usage pattern tracking. The business service method (UsageLog) in the business service (Usage Pattern Service) of the action set is called when the events occur.

This task is a step in Process of Configuring Usage Pattern Tracking.

To associate the action set with events

Navigate to the Administration - Runtime Events screen, then the Events view.

In the Events list, create a new record for each event, and complete the necessary fields.

Some of the fields are described in the following table.

Field	Comments
Sequence	Type a number to denote order in which the action set associated with the event executes relative to the other action sets associated with the event.
Object Type	Select the appropriate object type for the event. Values include: Applet, Application, and BusComp.
Event	Select the appropriate event. The object type that you select determines the events that are available for selection. For information about the descriptions of event values, see Siebel Personalization Administration Guide. The following events for all object types are available for usage pattern tracking: UPTGeneric. This event occurs when the server calls the TriggerUPTEvent application programming interface (API). UPTClientScript. This event occurs when a client script, such as a browser script or JavaScript, calls the TriggerUPTEvent application programming interface (API). For more information, see Browser Script Application Programming Interface and JavaScript Application Programming Interface. UPTServerScript. This event occurs when a server script calls the TriggerUPTEvent application programming interface (API). For more information, see Server Script Application Programming Interface.
Action Set Name	Select the action set name that you create in Creating Action Sets for Events of Creating Action Sets for Events.
Conditional Expression	Type a conditional expression to refine the data that applies to the event. You can click the select button in this field to access the Expression Designer dialog box where you can construct the expression. For example, if you want to monitor the event for only specific users, then you can specify those users in a conditional expression.

Usage Pattern Collection

Restart the sieb server, login, and then continue with the use case for which the usage log is required. The usage log is stored under the following folder:

siebsrvr\upt\$username$

Processing Usage Pattern

To process usage pattern tracking, perform the followings tasks:

Activating the Workflow for Usage Pattern Tracking

Complete the procedure in this topic to activate the workflow for usage pattern tracking. You designate this workflow in the job parameters of the component job that runs to capture information about usage pattern tracking.

This task is a step in Process of Setting Up Usage Pattern Tracking.

To activate the workflow for usage pattern tracking

Complete the following steps to make sure that the appropriate component group and the appropriate component in that component group are enabled:
1. Navigate to the Administration - Server Configuration screen, Enterprises, and then the Component Groups view.
2. Make sure that the Workflow Management component group is enabled.
  
  When you select the record for this component group, the components associated with the component group appear in the Components list. The Workflow Process Batch Manager component in this component group must be active and enabled.
Navigate to the Administration - Business Process screen, Workflow Deployment, and then the Active Workflow Processes view.
In the Repository Workflow Processes list, select the UPT Process workflow.
Click Activate.

Creating Job Templates for Usage Pattern Tracking

Complete the procedure in this topic to create a template for the component job that captures information about usage patterns.

This task is a step in Process of Setting Up Usage Pattern Tracking.

To create a job template for usage pattern tracking

Navigate to the Administration - Server Configuration screen, then the Job Templates view.

In the Job Templates list, create a new record, and complete the necessary fields.

Some of the fields are described in the following table.

Field	Comments
Name	Type a name of UPT Job Template.
Short Name	Type a short name of UPT JT.
Component	Select the Workflow Process Batch Manager component. Additional fields in the job template record are automatically populated. Do not change these default values.

In the Job Parameters list, create two parameters as follows:
1. Select Method Name in the Name field of the first job parameter.
  Additional fields in this job parameter record are automatically populated.
2. Select Workflow Process Name in the Name field of the second job parameter, and enter UPT Process in the Value field.
  
  Additional fields in this job parameter record are automatically populated.

Creating Component Jobs for Usage Pattern Tracking

You use the job template for usage pattern tracking to create a component job for usage pattern tracking. This component job captures information about usage patterns. You can set this component job to run only once at scheduled date and time or to run at regular time intervals that you specify. For information about administering component jobs, including creating, starting, deleting, cancelling, holding, resuming, and troubleshooting such jobs, see Siebel System Administration Guide.

This task is a step in Process of Setting Up Usage Pattern Tracking.

To create a component job for usage pattern tracking

Navigate to the Administration - Server Management screen, then the Jobs view.
In the Jobs list, create a new record, and select UPT Job Template in the Component/Job field.
The job parameters that you set up in the job template appear in the Job Parameters list. Do not change these parameters or add more parameters to the list.
Populate additional fields in the Job Detail form as necessary.

These fields define how frequently the job is run and the conditions under which the job is run. The number of events that you include in usage pattern tracking and the anticipated level of user activity determine the appropriate values for these fields. For more information about these fields, see Siebel System Administration Guide.

Viewing Usage Patterns

After the component job for usage pattern tracking runs, information about user events and event details appears in the Usage Pattern Tracking view of the Administration - Application screen.

This view contains the data about usage pattern tracking that is stored in the S_USER_EVENT table and the S_USER_EVT_DTL table. The number of records in these tables depends on the events that you configure for usage pattern tracking. It is recommended that you periodically move data from these tables. Your movement frequency depends on available memory and the level of user activity.

For reporting purposes, you can click the cogwheel icon and select the Export option to export the data from the Usage Pattern Tracking view to another application, such as Microsoft Excel.

To view usage patterns

Navigate to the Administration - Application screen, then the Usage Pattern Tracking view.

In the User Events list, view information about the events associated with users.

Some of the fields are described in the following table.

Field	Comments
User Name	Displays the user ID of the user who completed the event.
Session Id	Displays the ID of the session in which the user completed the event.
Event Name	Displays the name of the event that the user completed.
Event Start Date	Displays the date and time that the user started the event.
Event End Date	Displays the date and time that the user ended the event.

In the User Event Details list, view details about a selected event.

Details of Records for Usage Pattern Tracking

Administrators can review the details of records for usage pattern tracking in their work to generate reports for this feature. An example of the structure and attributes of a record for usage pattern tracking in the Siebel database follows:

<UPT>
	<Object Type> ; Application
	<Object Name> ; Siebel Universal Agent
	<Event Name> ; UPTServerScript
	<Event Source> ; Server Script
	<Event Context> ; Test UPT
	<Event Start Date> ; 07/30/2015 11:41:46
	<Event End Date> ; 07/30/2015 11:43:31
	<UPT Details> ; 
		<Detail1>
			<Name> ; Test UPT Name
			<Value> ; Test UPT Value
		</Detail1>
		</UPT Details>
</UPT>

Information about the content in this structure follows:

The Object Type attribute is a value of Applet, Application, or BusComp.
The Object Name attribute is the name of the object.
The Event Name attribute is a value selected from the Events view of the Administration - Runtime Events screen.
The Event Source attribute is Browser Script, Server Script, or a user-defined value.
The Event Context attribute is a short description of the event context.
The Event Start Date attribute is a value that the Siebel application defines, and its format depends on the format in the locale setting. You cannot change this value.
The Event End Date attribute is a value that the Siebel application defines, and its format depends on the format in the locale setting. You cannot change this value.
The Name attribute is a name that provides more information about the event context.
The Value attribute is a value that provides more information about the event context.

Application Programming Interfaces for Usage Pattern Tracking

This topic includes information about the application programming interfaces (APIs) for usage pattern tracking.

For more information about APIs for UPT, see:

Browser Script Application Programming Interface

The browser script application programming interface (API) follows:

theApplication(). TriggerUPTEvent (inputPropSet)

Example code for this API follows:

var uptRecord = CCFMiscUtil_CreatePropSet();

var details = CCFMiscUtil_CreatePropSet();

uptRecord.SetType("UPT");

uptRecord.SetProperty("Object Type", "Application");

uptRecord.SetProperty("Object Name", "Siebel Universal Agent");

uptRecord.SetProperty("Event Name", "UPTClientScript");

uptRecord.SetProperty("Event Sub Name", "Test");

uptRecord.SetProperty("Event Source", "Client Script");

uptRecord.SetProperty("Event Context", "Test UPT");

details.SetType("UPT Details");

details.SetProperty("Detail1", "Test UPT Value1");

details.SetProperty("Detail2", "Test UPT Value2");

uptRecord.AddChild(details);

theApplication().TriggerUPTEvent(uptRecord)

Information about the input property set follows:

The Object Type property is a value of Applet, Application, or BusComp. This default value is Application.
The Object Name property is a value that you specify. The default value is the application name from the configuration file.
The Event Name property is a value of UPTGeneric, UPTClientScript, or UPTServerScript. The default value is UPTClientScript.
The Event Sub Name property is a value that you specify. You can specify no value.
The Event Source property is a value that you specify. The default value is Client Script.
The Event Context property is a value that you specify.

JavaScript Application Programming Interface

The JavaScript application programming interface (API) follows:

SiebelApp.S_App.TriggerUPTEvent(inputPropSet)

Example code for this API follows:

var uptRecord = CCFMiscUtil_CreatePropSet();
var details = CCFMiscUtil_CreatePropSet();
uptRecord.SetType("UPT");
uptRecord.SetProperty("Object Type", "Application");
uptRecord.SetProperty("Object Name", "Siebel Universal Agent");
uptRecord.SetProperty("Event Name", "UPTClientScript");
uptRecord.SetProperty("Event Sub Name", "Test");
uptRecord.SetProperty("Event Source", "Client Script");
uptRecord.SetProperty("Event Context", "Test UPT");
details.SetType("UPT Details");
details.SetProperty("Detail1", "Test UPT Value1");
details.SetProperty("Detail2", "Test UPT Value2");
uptRecord.AddChild(details);
SiebelApp.S_App.TriggerUPTEvent(uptRecord)

Information about the input property set follows:

The Object Type property is a value of Applet, Application, or BusComp. This default value is Application.
The Object Name property is a value that you specify. The default value is the application name from the configuration file.
The Event Name property is a value of UPTGeneric, UPTClientScript, or UPTServerScript. The default value is UPTClientScript.
The Event Sub Name property is a value that you specify. You can specify no value.
The Event Source property is a value that you specify. The default value is Client Script.
The Event Context property is a value that you specify.

Server Script Application Programming Interface

The server script application programming interface (API) follows:

TheApplication(). TriggerUPTEvent (inputPropSet)

Example code for this API follows:

var uptRecord = TheApplication().NewPropertySet ();
var details = TheApplication ().NewPropertySet ();
uptRecord.SetType("UPT");
uptRecord.SetProperty("Object Type", "Application");
uptRecord.SetProperty("Object Name", "Siebel Universal Agent");
uptRecord.SetProperty("Event Name", "UPTServerScript");
uptRecord.SetProperty("Event Sub Name", "Test");
uptRecord.SetProperty("Event Source", "Server Script");
uptRecord.SetProperty("Event Context", "Test UPT");
details.SetType("UPT Details");
details.SetProperty("Detail1", "Test UPT Value1");
details.SetProperty("Detail2", "Test UPT Value2");
uptRecord.AddChild(details);
TheApplication().TriggerUPTEvent(uptRecord)

Information about the input property set follows:

The Object Type property is a value of Applet, Application, or BusComp. This default value is Application.
The Object Name property is a value that you specify. The default value is the application name from the configuration file.
The Event Name property is a value of UPTGeneric, UPTClientScript, or UPTServerScript. The default value is UPTServerScript.
The Event Sub Name property is a value that you specify. You can specify no value.
The Event Source property is a value that you specify. The default value is Server Script.
The Event Context property is a value that you specify.