7Usage Pattern Tracking

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:

  1. Setting System Preferences for Usage Pattern Tracking

  2. Configuring Usage Pattern Tracking

Note: You must perform a 18.9 repository upgrade to capture user actions with usage pattern tracking and user input recording.

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

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

  2. Set the system preferences in the following table.

    System Preference

    Description

    Enable UPT

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

    UPT Max Record Cache

    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 10,000.

    UPT Log Path

    This is relevant only for Bulk Mode recordings, where the volume of recording is high. All user actions and user inputs from the user interface are recorded when Bulk Mode recording is enabled. This is the network share to store UPT records in .csv files. This setting overwrites the default location siebsrvr\upt when a valid network is specified. For more information about enabling Bulk Mode (background) recording, see Capturing User Actions with Usage Pattern Tracking.

  3. 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 created in Step a, and separate each name with a comma.

  4. 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.

Creating Action Sets for Events

An action set includes the actions that are run 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 Configuring Usage Pattern Tracking.

To create an action set for events
  1. Navigate to the Administration - Runtime Events screen, then the Action Sets view.

  2. 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.

  3. 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 Configuring Usage Pattern Tracking.

To associate the action set with events
  1. Navigate to the Administration - Runtime Events screen, then the Events view.

  2. 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 the order in which the action set associated with the event runs 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:

    Action Set Name

    Select the action set name that you created 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.

Capturing User Actions with Usage Pattern Tracking

User actions, such as editing field data, selecting a record or entering a keyboard shortcut, are activities that the user does in the application UI before the next request reaches the server. Administrators can configure the application to capture user actions in the sequence in which they occur. This is in addition to existing usage pattern data that is captured. This topic describes how to enable the capturing of user actions.

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

Note: The feature described in this topic is available in Siebel CRM 18.9 Update and later releases.

You can capture UPT data in either Unit Mode or Bulk Mode. The following table describes each mode by highlighting the differences between them.

Unit Mode Bulk Mode

User initiated recording.

Recording in the background

Controlled by the end user using the Recording Panel

End user has no control (neither start nor stop) over the recording.

Recording is captured for one process or script at a time.

Continuous recording until stopped by the administrator.

Typically used by business administrators, test script authors, training manual writers, and so on.

Typically enabled for call center agents and other application users.

Generates logs for one recording at a time.

Generates a large amount of data.

To enable user action recording
  1. Navigate to the Administration - Runtime screen, then the Action Sets view.

  2. In the Action Sets list, query for the record: Recording.

  3. Select the Unit Mode/Bulk Mode action and set the value for the Unit Mode/Bulk Mode profile attribute to TRUE.

    The value for the Unit Mode/Bulk Mode attribute is correctly set.

  4. (Optional) Add a Siebel conditional expression to control whether recording is enabled for a specific user or set of users.

    According to the value set in the previous step, Unit Mode/Bulk Mode will be enabled or disabled for all users when the conditional expression is not used.

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

  6. In the Events list, create a new record for an event, and complete the following fields:

    Field Comments

    Sequence

    Type a number to denote the order in which the action set associated with the event runs relative to the other action sets associated with the event.

    Object Type

    Select the object type: Application

    Event

    Select the event: Recording.

    Action Set Name

    Select the action set name created in Creating Action Sets for Events. This is the action set you create in the business service called Usage Pattern Service.

    The event called Recording is created.

  7. Create an event for the object types whose events need to be tracked.

  8. Go to the Applet menu and click Reload Runtime Events.

  9. Log out of the application and then back in again for the changes to take effect.

Note: You can use the Unit Mode action for Enhanced UPT-KWD Recording Setup. It is recommended that you do not enable both Unit Mode action (a user-initiated recording) and Bulk Mode action (a background recording) for the same user. Users can see the recording bar with recording ON when both Unit Mode or Bulk Mode settings are in place. For more information on Record/Play automation, see Testing Siebel Business Applications.

Restricting User Action Recording to Specific User or Responsibility

You can restrict user action recording to specific users or user responsibility. The examples in the following procedure show you how to restrict user action recording.

To restrict user action recording to specific users or responsibility
  1. Navigate to the Administration - Runtime screen, then the Action Sets view.

  2. In the Action Sets list, query for the recording: Recording.

    The following use case scenarios are for illustrative purposes only. There are multiple ways to write Siebel expressions.

    • Use Case 1: To enable Unit Mode recording for all users:

      • Select the Unit Mode action and set the value for the Unit Mode profile attribute to TRUE.

      • Select the Bulk Mode action and set the value for the Bulk Mode profile attribute to FALSE.

    • Use Case 2: To enable Bulk Mode recording for all users:

      • Select the Unit Mode action and set the value for the Unit Mode profile attribute to FALSE.

      • Select the Bulk Mode action and set the value for the Bulk Mode profile attribute to TRUE.

    • Use Case 3: To enable Unit Mode and Bulk Mode recording for all users:

      • Select the Unit Mode action and set the value for the Unit Mode profile attribute to TRUE.

      • Select the Bulk Mode action and set the value for the Bulk Mode profile attribute to TRUE.

    • Use Case 4: To enable Unit Mode recording and restrict recording based on the Test Administrator user responsibility:

      • Create a Test Administrator responsibility and add some users to the responsibility.

      • Select the Unit Mode action and set the value for the Unit Mode profile attribute to TRUE, then add the following conditional expression:.

        InList('Test Adminstrator',GetProfileAttrAsList('User Responsibilities'))
      • Select the Bulk Mode action and set the value for the Bulk Mode profile attribute to FALSE.

      This enables user action recording (where the camcorder will be visible) only for those users who have the Test Administrator responsibility.

    • Use Case 5: To enable Bulk Mode recording and restrict recording based on the Test Administrator user responsibility:

      • Create a Test Administrator responsibility and add some users to the responsibility.

      • Select the Unit Mode action and set the value for the Unit Mode profile attribute to FALSE.

      • Select the Bulk Mode action and set the value for the Bulk Mode profile attribute to TRUE, then add the following conditional expression:

        InList('Test Adminstrator',GetProfileAttrAsList('User Responsibilities'))

      This enables Bulk Mode recording only for those users who have the Test Administrator responsibility.

Controlling User Input Recording

This topic describes how to control user input data, which is part of UPT records.

Data entered by users in the application UI is captured in UPT logs when Unit Mode/Bulk Mode is enabled. For certain deployments however, to ensure security compliance for example, user input data should not be stored in UPT logs. Administrators must decide whether to capture user input data in UPT logs or not. Administrators control this by configuring the Input Capture action and optionally a Siebel conditional expression (which controls the behavior at a granular level) in the application.

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

Note: The feature described in this topic is available in Siebel CRM 18.9 Update and later releases.
To control user input recording
  1. Navigate to the Administration - Runtime Events screen, then the Action Sets view.

  2. In the Action Sets list, query for the record: Recording.

  3. Select the Input Capture action, and set the Input Capture profile attribute to FALSE.

  4. (Optional) Add a Siebel conditional expression to control whether the recording is of a specific user or a set of users.

    According to the value set in the previous step, user input data is captured in the UPT log for all users when the conditional expression is not used.

  5. Go to the Applet menu and click Reload Runtime Events.

  6. Log out of the application and then back in again for the changes to take effect.

    After you log back in to the application, user entered data will no longer be seen in UPT logs.

Note: If the Input Capture action is set to FALSE to mask sensitive information, then KWD scripts will be generated without any input values. KWD scripts without input values fail on play back. However, you can add input values in the Test Script view.

Interpreting User Actions from Usage Pattern Tracking Data

This topic describes how user actions are recorded in the UPT logs.

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

Note: The feature described in this topic is available in Siebel CRM 18.9 Update and later releases.

User actions are captured in the UPT log as uaseq1, uaseq2, and so on, and are recorded under UPT Details. The following template is an example of how user actions are structured in the UPT log file, and the following table explains some of the log information:

    <UPT Details> 
        <uaseq1>
            <EUA> 
                <ParentRN>
                <CurrentRN>
                <OT>
                <Value>
            </EUA>
        </uaseq1>

        <uaseq2>
            <OUA>
                <ParentRN>
                <Type>
                <Operation> 
            </OUA>
        </uaseq2>
    </UPT Details>

The following table explains some of the log information:

Log Information Description

uaseq1

All user actions are captured in the order in which the user rns actions in the application. The user actions are recorded sequentially, uaseq1, uaseq2, and so on.

EUA

This is an explicit user action with user input.

ParentRN

The repository name.

CurrentRN

The repository name of the current interface control on which the user is performing an action.

OT

The object type in which the user is performing the action.

Value

The value entered by the user.

OUA

Other User Action.

Type

This is a type of action where user input is required.

Operation

This is a user action such as a mouse click, or a keyboard shortcut.

The following is an example of UPT log data. In this example, the log file contains a record of a user updating the Location field in an Account applet:

@0`0`5`0`EUA`3``ParentRN`SIS Account List Applet`CurrentRN`Location`OT`JText`Value`San Francisco`rowid`4`

Also in this example, the following five user pattern tracking properties and the respective values are recorded:

  • ParentRN: SIS Account List Applet

  • CurrentRN: Location

  • OT: JText

  • Value: San Francisco

  • rowid: 2

Note: A grave accent (`) acts as a delimiter between the properties and the respective values. A sequence of tilde (~) , vertical bar (|) and caret (^) acts as a delimiter between two actions: ~|^

Usage Pattern Collection

Restart the Siebel server, login, and then continue with the use case for which the usage log is required. The usage log is stored in the network path specified by the UPT Log Path system preference, or in the following default location: siebsrvr\upt\$username$.

Unit Mode recordings are always stored in the default location. Bulk Mode recordings are stored in the UPT Log Path (if set) or in the default location.

Note: The feature described in this topic is available in Siebel CRM 18.9 Update and later releases.

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

  1. 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.

  2. Navigate to the Administration - Business Process screen, Workflow Deployment, and then the Active Workflow Processes view.

  3. In the Repository Workflow Processes list, select the UPT Process workflow.

  4. 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

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

  2. 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.

  3. 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

  1. Navigate to the Administration - Server Management screen, then the Jobs view.

  2. 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.

  3. 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

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

  2. 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.

  3. 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.