Skip to main content

         This documentation site is for previous versions. Visit our new documentation site for current releases.      

This content has been archived and is no longer being updated.

Links may not function; however, this content may be relevant to outdated versions of the product.

About the 4.2 System Usage History Report

Updated on April 25, 2019


The System Usage History report (available in the Monitor Servlet in Version 4.2) reflects default definitions in many Pegasystems licenses. This article describes the report and the terms that it uses.

However, these terms may have other definitions in your situation. If desired, you can modify the standard System Usage History report .


Suggested Approach

Standard System Usage History Report

The System Usage History option displays a report summarizing monthly system usage over the last 13 months. (The last column contains data for the current month, which will display month-to-date data.)  You can use this report to verify license agreement compliance.

Note:  This report summarizes usage for all users and all nodes who are using a single PegaRULES database.  If some users access another database, they are not counted in the same report.

Rows of the report differentiate between Named Users and Invocations.  This distinction is determined in the Operator ID instance.  On the Security tab, the License Type field contains a drop-down list that presents these two types:

  •  Named users are people who use an application on a regular basis for their work (a call center, a health insurer, a bank, etc.).  Each of these users has a unique Operator ID (Data-Admin-Operator-ID instance), and they create and process some form of work objects.
  • Invocations, identify "users" that invoke the system through one ID or through an external system.  For example, an external system call uses the Process Commander server to perform processing (run activities, look up information).  Another example might be a company that sets up an application where users would use it infrequently and irregularly (such as a company suggestion box), where all the accesses would be through one ID.  (Note that one invocation may execute one or many flows, and may also execute non-flow rules.)

The System Usage report breaks down Named Users and Invocations further:

Report Category



Regular Named Users

Named users actively logged in (not passivated*) for four hours or more during any day of the month. Each regular named user represents a unique user.

A named user is included in this count if they were logged in for four or more hours on any one day (or more) during the month. The four hours does not have to be sequential; the user could log in for two hours in the morning and two hours in the evening, and would still be included in the count.  If a user is active from 9:40 to 11:30, and later from 2:10 to 2:20, they are counted as a regular user who is recorded during hours 9, 10, 11, and 14.

In addition, a named user is included in this count if they have Allow Rule Check out checked in their Operator ID instance, and logged in at least once during the month. Such named users are included in the count no matter how many hours they have spent working in the system.

Occasional Named Users

Named users actively logged in (not passivated) for less than four hours during any day of the month. Each occasional named user represents a unique user.


BPM Invocations

A count of invocations where one or more flow rules is executed.

NOTE:  This counter tracks invocations, not flow rule executions.  As stated above, one invocation may involve more than one flow rule execution.

Rule Invocations

A count of invocations where no flow rule is executed.

Users in Peak Hour

This count will show the maximum number of users who were signed on during any one-hour period in the month.  The one hour is measured by “clock time” – i.e., from 2:00 to 3:00.  The users do not all have to be concurrent – if one user were signed on at 1:30, and signed off at 2:30, and another user signed on at 2:45, and signed off at 3:15, they would both be counted for the 2:00 – 3:00 hour timeframe.

* Passivation is the act of writing a user instance to the PegaRULES database, for example, when the requestor session times out.  The data is stored in the database so that memory is freed for other users, and can later be restored to the requestor session once the user has re-authenticated.  The System Usage report does not count the time the user's requestor is passivated.


1. The definitions presented here are the standard definitions.  The terms Named User, Invocation, and so on may have a different definition in your Pegasystems license agreement

2. For all of the above categories, the counts show the number of users who were signed on during various one-hour periods in the month.  The hour is measured by “clock time” – i.e., from 2:00 to 3:00.  This means:

  • the usage does not have to be concurrent – if one user were signed on at 1:30, and signed off at 2:30, and another user signed on at 2:45, and signed off at 3:15, they would both be counted for the 2:00 – 3:00 hour timeframe.   
  • if a user’s time extends from one clock hour into the next, they are counted for two hours of use.  If a user logs in at 2:55 and logs out at 3:10, they are counted for two hours of use – the 2:00 hour and the 3:00 hour.

Customizing the Report

In the standard System Usage report, the Named Users are divided into Regular and Occasional users, based on their usage.  For each user, the system determines the day of each month where the user spent the most time logged on.  The default threshold for the Named Users is four hours.  If a user is logged in for four or more hours on their Peak Day, they are counted as a Regular user; less than four, and they are counted as an Occasional user.

You can change this default threshold by setting the RegularUserThreshold value in the pegarules.xml file.  The default value for this entry is 4, but any positive integer value is allowed.  This entry determines threshold for marking user as Regular or Occasional . Example pegarules.xml file entry:

<node name="Usage">
  <node name="HistoryReport">
                  <entry key="RegularUserThreshold" value="3"/>

With the above entry, any users who had more than 3 hours of usage in one day would be counted as a Regular user on the System Usage History report.

Customizing the Report - New Rule-Connect-SQL Instances

The report in the Monitor Servlet uses a direct query to the database.  V4.2 contains standard Rule-Connect-SQL rules that you can copy and modify to build a custom System Usage History report. There are four reports and three supported databases, so 12 distinct Connect SQL rules are provided.

Report Name



used for Regular and Occasional Named Users


used for BPM invocations


used for Rule invocations


used for Users in Peak Hour

Note that the SQL code is different for each type of database; therefore, there is a Rule-Connect-SQL instance for each database vendor. Example:

  • SystemUsageHistoryNamedUsersByPeakDay - Microsoft SQL Server
  • SystemUsageHistoryNamedUsersByPeakDay - DB2
  • SystemUsageHistoryNamedUsersByPeakDay - Oracle

The report name to be used is the Request Type key part of the Rule-Connect-SQL instance, and the database type is the Package Name key part:


The SQL code that defines the report is on the Open tab. The other tabs are empty.

When customizing this code, determine how you want to view the results:

  • through the Monitor Servlet
  • using a third-party reporting tool

Viewing a Custom System Usage Report through the Monitor Servlet

If you wish to use the Monitor Servlet to display the custom report, copy and override the Rule-Connect-SQL instances listed above. 

  1. Choose the line or lines of the report to be customized. 
  2. Open the appropriate Rule-Connect-SQL instance for the report to be customized ( Request Type ) and the database being used ( Package Name ). 
  3. Perform a "Save as" on this instance, changing the Request Type name to something appropriate for the application (For example, AcmeBPMInvocations").
  4. Customize the SQL code as desired, and save the form.
  5. Test

Important: Your SQL must be result-set compatible with the standard SQL. When overriding the SQL for use in the Monitor Servlet, it is imperative that the result set of the SQL not change.  The Java code that produces this report in the Servlet relies on both the names and number of the returned columns, and is also sensitive to the number of returned rows.  The default Monitor Servlet report covers 13 full months of history, as well as current month-to-date.  Your custom SQL query does not need to return exactly 14 columns, but it must not return more than 14 columns.

The result sets of each of the built-in queries are shown below.  Note that upper and lower case references must be reproduced exactly.


  • Year (4 digit - e.g. 2003)
  • Month (2 digit - e.g. 02, 11, etc.)
  • Operator (Data-Admin-Operator-ID name)
  • UsageHours (number of aggregated hours for this user for this year/month period)


  • Year (4 digit - e.g. 2003)
  • Month (2 digit - e.g. 02, 11, etc.)
  • Count (count of the number of BPM rule engine invocations during the month - regardless of operator)


  • Year (4 digit - e.g. 2003)
  • Month (2 digit - e.g. 02, 11, etc.)
  • Count (count of the number of Rule engine invocations during the month - regardless of operator)


  • Year (4 digit - e.g. 2003)
  • Month (2 digit - e.g. 02, 11, etc.)
  • Count (maximum number of users during the month)

Changing the pegarules.xml file

After customizing the SQL, you must add an entry (or entries) into the CustomQuery node in the Usage section of the pegarules.xml file, so the system knows to use the Rule-Connect-SQL instance.

The Package Name information (examples: "Oracle", "DB2") must be included as a sub-node.

There are four entries, corresponding to the System Usage History reports:

  • NamedUserCount
  • BPMInvocationCount
  • RuleInvocationCount
  • PeakUserCount

Enter only those Rule-Connect-SQL instances that you customized in the pegarules.xml file. The value of each of the above entries will be the new name ( Request Type) of the customized Rule-Connect-SQL instance:

<node name="Usage">
   <node name="HistoryReport">
         <node name="CustomQuery">
               <!--  node name is the same as the vendor string for your JDBC driver -->
                 <node name="Oracle">
                       <entry key="NamedUserCount" value="AcmeCoNamedUserCount"/>
                        <entry key="PeakUserCount" value="AcmeCoPeakUserCount"/>

Viewing a Custom System Usage Report through a Third-Party Tool

If you do not wish to view the System Usage Report through the Monitor Servlet, you can write custom SQL in a third-party tool to create whatever report you like.

The pr4_log_usage table in the PegaRULES database maintains system usage data for each active requestor.  Rows of this table are the basis for the standard System Usage queries, and can be queried with custom report.  You can use the Rule-Connect-SQL instances as an example of how to summarize categories of users. 

In addition, the pr_operators table can be used to determine information about the user when inspecting or aggregating pr4_log_usage rows.  Information from the pr_operators table may be used to determine whether a user is a Named or Invocation user (using the .pyLicenseType column), and whether that user is allowed to check out rules ( .pyAllowRuleCheckOut column.)

Have a question? Get answers now.

Visit the Support Center to ask questions, engage in discussions, share ideas, and help others.

Did you find this content helpful?

Want to help us improve this content?

We'd prefer it if you saw us at our best. is not optimized for Internet Explorer. For the optimal experience, please use:

Close Deprecation Notice
Contact us