Skip to main content

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

More about JMS Listener data instances

Updated on November 23, 2022

EAR versus WAR deployment

JMS listeners operations depend on whether Pega Platform is deployed as an Enterprise application (EAR file) or a Web application (WAR file). See the Pega Community article Using MQ and JMS Services with Enterprise Application deployment, regarding EAR deployment and polling.

When and how JMS listeners run

Three settings affect how email listener requestors run. If your listener is not behaving the way you expect, examine the following:

  • Startup Option – The Properties tab contains the property that controls how the listener starts. If the Node Based startup option is selected, ensure that the desired node is added to the list. If Host Based startup is selected, ensure that the desired host is added to the list.
  • initServices/initJMS — At startup, Pega Platform starts execution of a JMS listener only if the prconfig.xml file or Dynamic System Settings parameter initServices/initJMS is set to "true." If you notice that your JMS listeners do not route messages, examine the setting to determine if the value is set to “false.”
  • Blocked — If the Blocked option on the Properties tab of the listener is selected, the listeners do not start when the Pega Platform nodes start and you cannot start them in Admin Studio.

Listener restart after service rule changes

Any change to the Service Email rule on the Service, Request, or Response tab requires that you restart the listener from . If you do not restart the listener, the changes do not take effect.

Application Properties for Request Messages

Pega Platform provides four application-specific JMS properties that the sender can use to provide information about the messages that are consumed by Pega Platform JMS services.


This JMS property identifies the third key part of a JMS service rule. You can use this property in the following two ways:

  • To set up one listener that listens for messages to be routed to multiple service rules in the same service package and service class. In this case, you can leave the Service Method field empty on the listener form and configure the sender to provide the third key to the rule with the PegaRULES_ServiceMethod property in the messages.
  • When limited to one queue, but you need multiple listeners to monitor a common queue. In this case, use the PegaRULES_ServiceMethod property to identify which listener will consume the message.

PegaRULES_UserID and PegaRULES_Password

These properties identify the user name and password of a valid user.

Typically, if the message-driven bean and the service rule are to run as an authenticated user, you specify the appropriate user on the JMS Properties tab of the JMS Listener form. Values provided in the message with the PegaRULES_UserID and PegaRULES_Password properties override the values specified on the JMS Properties tab.


When a JMS service sends a reply in response to a message, the listener uses this property to specify the ID of the session used by the requestor that processed the original message. If the sending application sends a reply in response to the service's response, it can use this property to specify that the same session be used to process this message. This mechanism allows the sending application and the JMS service to conduct stateful sessions.

Application Properties for Response Messages

When the service rule is configured to send a response, the listener adds property values for the following Pega Platform application-specific JMS properties to the message:

  • PegaRULES_ServiceMethod. If the request message contained a value for this property, the response message echoes the input value.
  • PegaRULES_SessionID. A string that identifies the session used by the requestor that processed the message.
  • PegaRULES_ServiceStatus. Specifies whether there were errors during the processing of the message. If errors occurred, this property is set to false. Otherwise, it is set to true.
  • PegaRULES_ErrorMessage. If the value of PegaRULES_ServiceStatus is set to false, this property contains the default, system-generated error message. Use the Response tab of the service rule if you want more information than the default error message to be sent in the response message.

The listener also sets a value in the JMSCorrelationID message header. By default, this value is copied from the JMSMessageID field from the request message.

  • Previous topic JMS Listener form - Completing the JMS Properties tab
  • Next topic About JMS MDB Listener data instances (Data-Admin-Connect-JMSMDBListener)

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