Applies to Pega Platform 7.2-8.5
This article provides answers to frequently asked questions about Operator Presence. This article also describes the changes implemented in Pega 8.5 and later versions.
Answers to Frequently Asked Questions
- Attempting to log in as an operator, I see the error message, The current session is blocked, as the maximum number of active sessions for the current operator has been reached. How do I resolve this issue?
- What is the reason for the occurrence of the ‘The message exceeds recommended size of 8000 (Size: 2846021). Topic: NM-DATA-ADMIN-OPERATOR-ID. Start of message: Class:Data-Admin-Operator-ID, Type:null, Context:{"StandardAttributes":{"OperatorID":"mashupuser","N...’ error in logs?
- How to query a Presence record?
- Why are the Custom attributes on my operator record not cleared even after I have logged out from the session?
- Why does illegalStateException with the following error occur in logs: "Exception;java.lang.IllegalStateException: Unable to retrieve attribute definition for a field.Tenantshared FieldIndex:2 MapContents:attributeTocacheFieldMapper:; {shared|CustomerService|.CustomAttributes.CSRStatus:0}” ?
- Is it okay to disable Operator Presence?
Deviations from Hazelcast implementation in Pega 8.5 and later versions
Introduction
Operator Presence tracks the real-time connection status of operators so that you can route work to operators that are online and available. The Presence record holds the aggregated state of an operator along with other Standard attributes. It contains information related to all the sessions of an operator. The option to set Custom attributes to an operator is also available.
Operator Presence data is stored in the Distributed Maps of Hazelcast in Pega 8.4 and earlier versions. Presence data is stored in the database in Pega 8.5 and later versions.
Answers to Frequently Asked Questions
Attempting to log in as an operator, I see the error message, The current session is blocked, as the maximum number of active sessions for the current operator has been reached. How do I resolve this issue?
The reported error occurs when the number of current sessions logged in by the user exceeds the value configured for the maximum number of Active sessions which is an expected behavior (applicable to all the Pega releases).
In this scenario, verify if you have any active sessions. If yes, verify the number of active sessions.
For information related to configuring the maximum number of Active sessions for an operator, refer the Specifying the number of concurrent sessions article.
The number of Active sessions count is fetched from the Operator Presence record. Scenarios such as Split Brain of Hazelcast cluster occur when an operator session is updated incorrectly and you are blocked from logging into the application.
To address this issue, invoke the following API from Java step by passing the operator ID to the API: pega.getSystemOperationsProvider().getPresenceSessionManagementAPI().clearPresenceSessions(operatorId);
Split Brain of Hazelcast cluster issue does not occur on Pega 8.5 and later versions because Presence storage is moved to database.
What is the reason for the occurrence of this error in logs: The message exceeds recommended size of 8000 (Size: 2846021). Topic: NM-DATA-ADMIN-OPERATOR-ID. Start of message: Class:Data-Admin-Operator-ID, Type:null, Context:{"StandardAttributes":{"OperatorID":"mashupuser","N..." ?
The Pega Web Mashup is configured to use a Template operator. A new entry is added to the Template Operator’s Presence record each time the Mashup loads. This results in the increase in the size of the Operator Presence record. Hence, the error occurs.
This issue is addressed in Pega 8.3.4 and Pega 8.4.2. Any operator with more than 10 active sessions is added to the BlackList operator Dynamic System Setting (DSS).
Alternatively, perform the following local change:
Place the operator on the deny list by adding the operator ID to the following Data Admin System Setting (DASS) manually:
Short Description: operatorpresence/blacklisted/operators
Owning RuleSet: Pega-Engine
Setting Purpose: operatorpresence/blacklisted/operators
This DASS is a comma-separated list of operator IDs.
Any operator added to this DASS setting is not considered for Operator Presence related flows.
The issue does not occur on Pega 8.5 and later releases because Presence storage is moved to database.
How to query a Presence record?
Presence Query Service provides Query clauses (for example, IN, CONTAINS, EQUALS clauses) that are similar to the Database clauses. To query the Operator Presence data, use the API provided in the Presence Service. Querying Presence data is similar to querying database.
Why are the Custom attributes on my operator record not cleared even after I have logged out from the session?
Custom attributes are cleared only if all the sessions of an OperatorID are logged out from the system. You can also clear the Custom attributes by invoking the following API in the Java step of the activity: tools.getPresenceService.clearCustomAttributes(OperatorId,CustomCategoryName);
Why does the IllegalStateException occur in logs
Exception;java.lang.IllegalStateException: Unable to retrieve attribute definition for a field.Tenantshared FieldIndex:2 MapContents:attributeTocacheFieldMapper:;
{shared|CustomerService|.CustomAttributes.CSRStatus:0}?
This issue occurs due to Hazelcast Cluster instability. To resolve the issue, perform a Cluster restart. However, the issue is addressed in Pega 8.2.
Is it okay to disable Operator Presence?
Do not disable Operator Presence. Some of the out-of-the-box features like Customer Service routing, Notification Gadget, and Max Concurrent sessions for each operator use Operator Presence.
Deviations from Hazelcast implementation in Pega 8.5 and later versions
Operator Presence data is stored in the Hazelcast Distributed map in Pega 8.4 and earlier versions. However, it is stored in the database in Pega 8.5 and later versions. Therefore, consider the following factors when working with Operator Presence in Pega 8.5 and later versions.
Fields not stored in Standard attributes
LoggedIn Time
SetAttributes API
User queries
APIs for fetching Presence records
Custom attributes not cleared during cleanup
Fields not stored in Standard attributes
The following fields are not stored in the Standard attributes:
- GeoLocation
Updating Geolocation in the OperatorRecord through special handling is not supported. - Operator name
Operator name is not stored in the Presence record. - Status
Status is plain text.
Status needs to be stored in the Custom attributes if it needs to be used.
LoggedIn Time
In the Hazelcast implementation, LoggedInTime is the oldest logged in time of all the sessions.
In the Database implementation, LoggedInTime is the oldest time of active sessions. If no active sessions exist, then LoggedInTime is empty.
SetAttributes API
The following two versions of SetAttributes API are available in the Hazelcast implementation:
- With overwrite
Existing data is overwritten with the data provided by user. - Without overwrite
Existing data is merged with the data provided by user.
In the Database implementation, only one API is present. The Clipboard page provided is merged with the existing Clipboard page.
Factors to consider
Consider the following factors when working with Custom attributes for Operator Presence:
- PageList properties are not supported in Custom attributes because merging PageList property values is not supported. However, PageGroup properties are supported in the Custom attributes.
- Custom attributes have a Pega class in Pega 8.5. This data can be obtained by performing Obj-Open and Obj-Save methods. However, do not perform Obj-Open and Obj-Save methods for the Custom attribute data. Use the Query API to obtain the data and the SetAttributes API to save the data. In the Hazelcast implementation, map is used instead of Pega class.
- To clear an attribute value, use the property.clearValue() API, instead of the Page.remove(prop) API.
User queries
User’s queries on Custom attributes apply only to active sessions.
APIs for fetching Presence records
The following API fetches the Presence record of a specific operator:
tools.getPresenceService().getPresenceRecord(String operatorId, String customCategoryClassName)
The following API fetches all the Presence records:
tools.getPresenceService().getAllPresenceRecords(String customCategoryClassName)
Custom attributes not cleared during cleanup
Custom attributes are not cleared during clean-up in cases of node crash and cluster restart. This occurs even though no sessions exist for an operator.
