Skip to main content

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

MQ Listener form - Completing the Listener Properties tab

Updated on November 23, 2022

Use the Listener Properties tab to configure listeners that monitor a specified queue of a WebSphere MQ server and route those messages to an MQ service. An MQ Listener instance provides access to all Service MQ rules with specified Service Package, Service Class, and Service Method key parts. (The second and third key parts are optional.)

Listener nodes

Start Option Select to control how listeners start:
  • Run on all nodes — The listener is run on all nodes and all servers in a cluster.
  • Node based startup — The listener is started only on specified nodes.
  • Host based startup — The listener is started on a specified number of nodes on specific servers within the cluster.
  • NodeClassification based startup — The listener is started on the specified node types.
Node ID Available when the Node based startup option is selected. In a multinode cluster, using the SmartPrompt, enter the node ID of the server host node or nodes where this listener will run. When a node starts it activates the listener on the current node if the current node matches any node in the list (and if other requirements are met).
  • If a node is specified, the current node must match a name in the list for the listener to be activated.
  • If a node is not specified, the listener is activated on each node. See More about MQ Listeners.

Operating a listener on multiple nodes can increase throughput.

Host Name Appears when the Host based startup option is selected. Enter the network location name of the host server on which the listener is to start.
Node Count Appears when the Server based startup option is selected. Enter a number of nodes on which the listener is to start.
Node type Appears when the NodeClassification based startup option is selected. Select a node type from the list or click the Plus icon to add another node type to the listener.
Reset Startup Deletes all the instances from the class Log-Connect-AssignedNodes, so that listeners can be started.

Listener properties

Message ID Optional. Enter a text value to use to filter arriving messages. Typically used only when testing an MQ service during development.

If a value is specified, the listener reads only messages with the specified value (converted to bytes) in the MessageID header field from the queue. Leave this field blank on a production system.

Correlation ID Optional. Enter a Single Value property reference or a literal constant in double quotes to use to filter messages arriving on the request queue. Typically used only when testing an MQ service during development.

If a value is specified, the listener reads only messages with the specified value (converted to bytes) in the CorrelationID header field from the queue. Leave this field blank on a production system.

Concurrent Threads Enter 1 or a small integer to determine the number of threads per server node that this listener requestor creates when it starts.

As a best practice, start by setting it to no more than two times the number of CPUs on the server. Then tune it for your application. Depending on what your application does, you may need to set it lower or higher.

Service Package Specify the first key part — the Customer Package Name — of a Service MQ service rule in this field. Use the Service Package, Service Class, and Service Method fields together to identify which Service MQ service rules will process the request messages.
Service Class Specify the second key part — the Customer Class Name — of the Service MQ rules that are to process the requests.
Service Method Optional. Specify the third key part — the Customer Method Name — of the Service MQ service rule that is to process the requests. If this field is blank, the listener obtains the third key part from the ApplicationIdData header field of each incoming request message.
Wait Interval (seconds) As this server is deployed in the Web tier, the listener cannot be shut down while it is listening to the queue ("sleeping"). Use this field to specify a regular interval, in seconds, when the listener pauses ("wakes up") and determines whether a shutdown request was sent.

Use Admin Studio to start and stop listeners. For more information, see Managing listeners and the Admin Studio help.

If this server is deployed in the Enterprise tier of a Java EE application server, enter a value in seconds to determine how often the listener polls the application server.

Test Connectivity Optional. After you complete this tab and save the data instance, click to confirm that your system can connect to the MQ server.

The system attempts to connect to the queue manager and access the message queue. No messages are accepted. The system presents test results in a separate window, identifying the parameters used in the test, the steps attempted, and the outcome of each step.

(If the Blocked check box is selected when you click this button, testing ends with a Failed message.)


Complete three fields to configure transacted message processing.

Transacted messaging can help ensure that a failed message is eventually processed, through repeated attempts. It requires that the MQ server have a backout queue. See the Pega Community article How to build an MQ Listener that supports transacted messaging for more information on this capability.

Transacted MessagingSelect to enable transacted message processing.
Threshold Specify the number of times the service rule attempts to process a message after failing to process it correctly. After this number of attempts, the listener routes the message to the backout queue specified in the Backout Queue field.
Backout Requeue Specify the name of the backout queue that the listener routes failed messages to when transacted message processing is enabled.

This field supports the Global Resource Settings syntax (= PageName.PropertyName ). The default property name for this field is pyRequeue. For more information, see Using the Global Resource Settings feature.

Requestor Log-in

Complete the following fields unless the MQ service processing can be accomplished as a guest requestor, without authentication.

Requestor UserID Optional. Select the Operator ID that MQ processing will use for processing associated with this listener. The access group associated with the Operator ID instance for this User ID determines RuleSets, security, work queues, and so on.
PasswordEnter a password for the Operator ID.


The Remote Logging feature streams the contents of the Pega log file to the LogFactor5 application installed on your workstation.

After you add your workstation as an active logger in Admin Studio, your workstation receives all messages for all processes running on the server. To specify that you want to view only those log messages that are about the service rule this listener listens for, complete the fields in this section. Remember to start the LogFactor5 window on your workstation before you use this form to identify your workstation as a logger.

Remote Host Optional. Enter the name of your computer. See also How to install and use remote logging
PortOptional. Enter the TCP/IP port number that the log4j package on your computer listens on. By default this port is 8887.

Startup status

Blocked Select to prevent this listener from being started by any means. If cleared, the listener starts with system startup, or can be started using the System Management application. See More about MQ Listeners.
  • Previous topic MQ Listeners - Completing the New or Save As form
  • Next topic MQ Listener form - Completing the Properties tab

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