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.

Tracking the online presence of operators

Updated on June 30, 2017

You can track the real-time connection status of operators so that you can route work to operators who are online and available. You can configure your Pega 7 Platform application to notify you when the online status of an operator changes, instead of repeatedly requesting the status.

When an operator logs in to an application, the Pega 7 Platform begins tracking the status of the requestor in the operator presence record, which maintains operator state information until the operator logs out of all sessions.

By default, each presence record captures operator status and connection information by using the following standard attributes. You use the PresenceService() API to configure these attributes.

  • Operator ID – Operator ID.
  • Operator_Name – Operator name.
  • State – Connection status of the operator. The values for this attribute are:
    • ACTIVE – The operator is currently logged in to the system.
    • AWAY – The operator session has timed out.
    • DISCONNECTED – The operator has been disconnected from the network because of one of the following events:
      • The operator closed the browser session without logging out of the system.
      • The operator browser session crashed.
      • The network connection is down.

      The operator status becomes ACTIVE when the network connection is restored or when the browser session is restored by the operator.

      The operator status of DISCONNECTED is available beginning with Pega 7.3.

    • OFFLINE – The operator is logged out of the system.
If the operator closes the browser, the operator status changes to DISCONNECTED immediately. However, if the operator is disconnected because of a browser crash or network disconnection, there is a slight delay in the status change of the operator. To change the default interval delay timing, see Changing the default interval delay timing for operator disconnect status.
  • Status – Current status of the operator, for example, "busy" or "do not disturb”. This attribute has no default value. You can update it by using the PresenceService() API.
  • Geolocation – Current geographical coordinates of the operator. You can update this attribute by using the PresenceService() API.
  • Sessions – List of sessions to which the operator is logged in.

To receive real-time notifications when the status information in the operator presence record changes, do one of the following actions:

  • Subscribe to the Operator Presence channel. The operator presence record sends status notifications to this system-defined channel. The communication between this channel and subscribers is based on the publish/subscribe (pub/sub) messaging pattern. For more information about pub/sub implementation in the Pega 7 Platform, see Real-time applications and push notifications in the Pega 7 Platform.
  • Use the PresenceService() API to query the presence record directly.

Receiving real-time status notifications by subscribing to a channel

  1. Optional: Define a category for custom operator record attributes. For example, you can add the custom operator statuses “Available on phone” and “In a meeting” to the standard status attributes.
    1. Use the setAttribute() method of the PresenceService() API to define your custom category and attributes. For more information, refer to the API documentation.
    2. Add the custom category to the Operator Presence channel.
      1. Click Designer Studio > User Interface > Notification channels.
      2. Click the Gear icon next to the Operator Presence channel.
      3. Click Add category, and enter the category name.
      4. Click Submit.
  2. Configure your application component to subscribe to the channel.
    1. Locate the dynamic layout that displays the operator information, such as the team gadget or the messaging app window.
    2. Select the layout, and click the Gear icon to open the layout properties panel.
    3. Click Actions.
    4. Click Create an action set.
    5. Click Add an event, and select On load under Other events.
    6. Under Subscribe, select Operator Presence from the Channel name list.
    7. Select a category.
    8. Select the source of the operators list.
  • Operators list – Select this option to add the list of operators manually.
  • Clipboard page – Select this option if the list of operators is available on a clipboard page.
  • Data page – Select this option if the list of operators is sourced from a data page.
  1. Click Add an action for callback to select the operation to be performed after receiving the updates.

When the status information for an operator is updated, the changes are automatically published to the Operator Presence channel. The channel broadcasts these updates to all subscribed application components. When subscribers receive these notifications, defined callback actions, such as running a specific activity, are automatically triggered to reflect operator real-time availability.

Querying directly to retrieve operator status

You can directly query the presence record to obtain on-demand status information, such as listing users within a particular location, by using the queryPresence() method of the PresenceService() API.

For example, to retrieve a list of operators whose status is “ACTIVE”, who can speak “French,” and whose status is not “AWAY", you can build three different clauses for each of these conditions. You join the clauses as shown in the following example:

PresenceQueryClause c1= PresenceQueryClause.Builder.createEqualsClause('A', PresenceQueryClause.STANDARD_CATEGORY, PresenceStandardAttributes.STATE.getName(), "ACTIVE", false);

PresenceQueryClause c2 = PresenceQueryClause.Builder.createEqualsClause('B',"CustomerService", "languages" , "French", false);

PresenceQueryClause c3 = PresenceQueryClause.Builder.createContainsClause('C', "CustomerService", "phone/status" , "AWAY", true);

List<PresenceRecord> records = tools.getPresenceService().queryPresence("A AND B AND C", Arrays.asList(c1,c2,c3), "CustomerService");

To view sample queries, refer to the FetchUsersPresenceByState activity Java code.

When you use the API to query or update status, you can convert the results to a JSON object by using the PresenceRecord.toJson() method.

Updating status and other attributes on demand

Update the status, location, and other custom attributes of an operator on demand with the tools.getPresenceService().setAttributes() method of the PresenceService() API.

For example, to update the status and other custom attributes of an operator called [email protected], invoke the API as described in the following example to set the status standard attribute and the language and phone/status custom attributes:

//prepare arguments to pass

HashMap<String,String> standardAttributes = new HashMap<>();

standardAttributes.put(PresenceStandardAttributes.STATUS.getName() , "Office");

HashMap<String,String> customAttributes = new HashMap<>();

customAttributes.put( "languages", "French");

customAttributes.put( "phone/status", "Available");

//invoke API

boolean status=false;


status = tools.getPresenceService().setAttributes("[email protected]", "CustomerService", customAttributes, standardAttributes);

} catch(PresenceException e){



return status;

Refer to the modifyUserPresenceAttributes activity Java code to view sample queries.

Changing the default interval delay timing for operator disconnect status

A client heartbeat mechanism polls web socket connections to monitor the connection status of operators. The following prconfig.xml file settings control polling frequency and client heartbeat threshold:

  • server-push/client-heartbeat/interval – Default value is 20 seconds.
  • operatorpresence/max-client-heartbeats-missable – Default minimum value is 2 heartbeats.

To reduce the interval delay timing for updating the operator disconnect status in the event of a network disconnection or browser crash, change the default values of these settings in the prconfig.xml file. If you update these settings, you must restart your system for the settings to take effect.

These settings can also be configured in Dynamic System Settings.

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