Applies to Pega Platform versions 7.2.2 through 8.5
Push Notification is a real-time notification system based on the publish or subscribe (pub or sub) messaging pattern where a node in the cluster can push notifications to browser clients. Nodes publish notifications to a channel that can broadcast to all the subscribed browser clients.
The Push Notification feature was introduced in Pega 7.2.2. Some users reported performance degradation that they erroneously ascribed to frequent PRPushServlet requests to the server and they disabled Push Notifications.
Do not disable the Push Notification feature unless assisted by Pega Product engineers and Global Client Support (GCS) engineers.
Correcting misperceptions about Push degrading performance
Answers to frequently asked questions
Correcting misperceptions about Push degrading performance
The Push feature in Pega supports WebSockets and HTTP long-polling. Since its introduction in Pega 7.2.2 there have been reports about performance impact because of frequent PRPushServlet requests to the server. To correct this alleged problem, users disabled the Push feature. This action is not advised.
The Push framework in Pega does not degrade performance because it uses the latest servlet 3.0 APIs, and many of the application servers and web servers support JSR356 and Servlet 3.0 features. Implementation of these standards does not hold any thread resource at the server.
Depending on the container implementation, Pega establishes WebSockets or falls back to HTTP long-polling.
For WebSockets, a persistent socket connection is established with the server and messages are delivered through that socket connection.
For HTTP long-polling Servlet 3.0, the Async Servlet feature delivers messages using suspend and resume, which works like this: When the browser sends a polling request to the server and there are messages that have to be delivered, the response is committed immediately. However, if there are no messages to deliver, the server suspends the request (that is, the thread is recycled for use by other requests in the container) until a message event commits the response. If no message event occurs, then the response is committed after the predefined timeout of 60 seconds.
The resources used to deliver messages are very minimal. Therefore, incorrectly assuming that HTTP long-polling affects performance and then disabling the Push feature is not the correct approach.
Testing of the Push feature in Pega’s performance testing lab showed that thousands of messages were delivered without any performance degradation.
Artifacts required for performance analysis
If your Pega deployment experiences performance degradation, attach the following artifacts to your Pega service request (Incident, INC):
- Memory profiling snapshot
- CPU profiling snapshot
- Logs for errors and exceptions
- Any analysis or specific behavior that you observed (Word document)
Answers to frequently asked questions
How do I configure Push Notifications?
Should I disable Push in my Pega environment?
How do I verify that Push is enabled?
Push is disabled in my environment. How do I enable it?
When I see many instances of the exception “Push is disabled”, what should I do?
Why do I see messages not published in a few nodes after I have enabled Push in my environment?
How do I verify that my subscription is established?
How do I verify that subscribers are receiving messages?
Why is a user receiving messages, but the UI is not being refreshed?
How do I fix WebSockets not working in JBoss?
When a PushRequest response contains HTTP status code other than 200, what should I do?
How do I trace Push Notifications?
What additional artifacts are needed in my service request (INC) to GCS?
How do I configure Push Notifications?
To configure Push Notifications, complete the following high-level procedures:
- Create a Notification Channel.
- Subscribe to the Notification Channel and add Callback events.
- Publish a message to the Notification Channel.
For more information, see Notification channels.
Should I disable Push in my Pega environment?
No. Push Notification is used by Pega-provided capabilities. Disabling Push Notification affects how other Pega capabilities succeed (or fail). If you are under the impression that Push Notification degrades performance, see Correcting misperceptions about Push degrading performance.
How do I verify that Push is enabled?
From Admin Studio, for all nodes or a specific node, verify that the value of the prconfig setting is server-push/enabled = true.
Push is disabled if the value of server-push/enabled = false.
WebSockets transport protocol verification for Push
HTTP long-polling protocol verification for Push
WebSockets transport protocol verification for Push
If WebSockets is the transport protocol, perform the following steps:
- Log in to the Pega system.
- From your browser, open Developer Tools.
- Refresh the screen.
- In Developer Tools, go to the Network tab and specify the filter WS.
The WebSocket connection is displayed if Push is using WebSocket as the transport protocol.
HTTP long-polling protocol verification for Push
If HTTP long-polling is the transport protocol, perform the following steps:
- Log in to the Pega system.
- From your browser, open Developer Tools.
- Refresh the screen.
- In Developer Tools, go to the Network tab and specify the filter PushServlet.
The HTTP long-polling connection is displayed if Push is using long-polling as the transport protocol.
Push is disabled in my environment. How do I enable it?
In the prconfig.xml file, check to ensure that this parameter is set: server-push/enabled = true.
If the value of this setting is set to false, change it to true.
Restart all application server nodes in the cluster after changing the value.
When I see the network trace warning message, “WebSocket failed on the first connection attempt. Downgrading to long-polling and resending”, what should I do?
This warning indicates that the default WebSocket connection is not getting established and that the fallback to HTTP long-polling connection will resend the message.
Contact GCS if you need assistance checking your application server compatibility for technologies supported by the container and technologies supported for Push.
For application servers supported by Pega, see the Platform Support Guide Resources.
When I see many instances of the exception “Push is disabled”, what should I do?
Verify that Push is enabled. See How do I verify that Push is enabled?
If Push is not enabled, follow these steps:
- Open the prconfig.xml file to edit it.
- Specify server-push/enabled = true.
- Restart all application server nodes in the cluster.
Why do I see messages not published in a few nodes after I have enabled Push in my environment?
You must restart all application server nodes in the cluster after Push is enabled.
How are subscribers notified?
Push Notifications use either WebSockets or HTTP long-polling to broadcast messages to subscribers. WebSockets is the default protocol. To override the WebSockets default setting, open the prconfig.xml file and specify the following parameter:
<env name="server-push/transport" value="long-polling"/>
How do I verify that my subscription is established?
Enable debug loggers for com.pega.pegarules.session.internal.serverpush.DefaultSubscriptionManager and load the section where the subscription is configured. Subscription details are logged in the PegaRULES log in the following format.
Added subscription with identifier: SubscriptionData[SubscriptionId=f186423d-1f18-45d6-bbcc-3638a9c55276,Subscriber=[RequestorId=HV29EEF6A3E9XBBUKPD8XGRFQ3SYLIPH1A,PortalName=pyCaseManager7,ThreadName=PS2__TABTHREAD1,TenantId=<null>,MainRequestorId=],ClassName=PegaSocial-Document,Settings=[ConditionName=pyCaseContext,ConditionValues=[PEGASOCIAL-DOCUMENT DOC-1]],LastUpdateTimeInMillis=1594619188200]
By enabling this logger, you can also get a list of Unsubscribe events.
How do I verify that subscribers are receiving messages?
WebSocket transport protocol verification for subscriber receipt of messages
HTTP long-polling protocol verification for subscriber receipt of messages
WebSocket transport protocol verification for subscriber receipt of messages
If WebSockets is the transport protocol, perform the following steps:
- Log in to the Pega system.
- From your browser, open Developer Tools.
- Ensure that the subscribed-to section in the Notification Channel is open.
- Refresh the screen.
- In Developer Tools, go to the Network tab and specify the filter WS.
- Publish a message.
See the message in the WebSocket connection.
HTTP long-polling protocol verification for subscriber receipt of messages
If HTTP long-polling is the transport protocol, perform the following steps:
- Log in to the Pega system.
- From your browser, open Developer Tools.
- Ensure that the subscribed-to section in the Notification Channel is open.
- Refresh the screen.
- In Developer Tools, go to the Network tab and specify the filter PushServlet.
- Publish a message. See the message in the response of the long-polling request.
- If the message is not visible in the response of the long-polling request, take the following action:
- In the console, set this parameter: pega.ui.debug=true
- Publish the message.
Why is the UI not refreshed when the message is published? I have subscription on a Notification Channel.
- Verify that you are receiving messages: How do I verify that my subscription is established? How do I verify that subscribers are receiving messages?
- Check the settings of the Other event On Load configured in the UI. See Creating an action set, Step 3.
- Check the name of the Filter property and the Filter value: How do I verify that subscribers are receiving messages? (Step 5 for either option)
Why is a user receiving messages, but the UI is not being refreshed.
Check the Callback event that is configured for the On Load event. See Creating an action set, Step 3.
How do I fix WebSockets not working in JBoss?
Consult the appropriate JBoss documentation for your needs: https://jbossas.jboss.org/
When a PushRequest response contains HTTP status code other than 200, what should I do?
Check the load balancer configuration and ensure that the load balancer is not blocking the Push requests.
See Understanding HTTP status codes for troubleshooting common issues.
How do I trace Push Notifications?
How can I enable Tracer settings?
What information is available in the Tracer event?
Can I use the Tracer tool?
Yes: Subscription and Publish can be traced using the Tracer tool.
How can I enable Tracer settings?
- In the footer of Dev Studio, click the Tracer icon.
- On the Tracer toolbar, click Settings.
- In the Tracer Settings window, the Events to trace section, select the check box for Push Notifications.
- For more information, see Configuring Tracer settings.
Alternatively, you can manage Trace for Push Notifications in Admin Studio: Click Resources > Requestors and select the Trace action. For more information, see Managing Requestors.
What information is available in the Tracer event?
For Subscriptions, the following information is available:
- Notification Channel
- Subscription Class
- Subscription Condition
- Subscription Data
For Publish, the following information is available:
- Notification Channel Name
- Source Page
- Published Page>
- Stack trace of publish
What additional artifacts are needed in my service request to GCS?
If you report an Incident (INC) to GCS for a Push Notification problem, attach the following artifacts to your INC:
- A link to this knowledgebase article or a PDF copy of it with your questions and notes included
- Fiddler or browser network trace
- PegaRules logs after enabling the required loggers
- Channel configuration screenshot
- Subscription configuration
- Publish configuration
Related Content
Enabling push notifications for a case type
Sending push notifications from cases
Learning about real-time applications and push notifications in Pega Platform