EAR versus WAR deployment

The operation of JMS listeners (not JMS MDB listeners) 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.

For an EAR deployment example, see the Pega Community article How to deploy a JMS Listener as a Message-driven bean.

When and how JMS MDB listeners run

Two settings affect how JMS MDB listeners run. If your listener is not behaving the way you expect, examine the following:

• initServices/initJMS — At startup, Pega Platform starts execution of a JMS MDB listener only if the prconfig.xml file or Dynamic System Setting 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 “false.”
• 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.

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 Admin Studio. If you do not restart the listener in Admin Studio, the changes do not take effect.

Application properties for request messages

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

PegaRULES_ServiceMethod

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 JMS MDB Listener form and configure the sender to provide the third key to a service rule with the PegaRULES_ServiceMethod property in the messages.
• When limited to one queue, but you need multiple listeners to monitor that queue. In this case, use the PegaRULES_ServiceMethod property to identify which listener is to consume the message.

PegaRULES_UserID and PegaRULES_Password

Two 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, specify the appropriate user on the JMS Properties tab of the JMS MDB Listener form. Values provided in the message with the PegaRULES_UserID and PegaRULES_Password override the values specified on the JMS Properties tab.

PegaRULES_SessionID

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 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 text 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 occur, 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 unless it is overridden in the data mapping on the Response tab of the service rule.