Setting Up Message Handlers
  • 05 Jul 2023
  • 2 Minutes to read
  • Dark

Setting Up Message Handlers

  • Dark

Article summary

Setting up a Listener/Message Handler

Message Handlers in Clustered Environment
In a clustered environment, users must configure the Message Handler on only one node. All the other nodes in the cluster automatically inherit the configuration.

To subscribe to messages in a queue, a Message Handler Flow needs to be configured. This will be used to interpret and run actions on messages received from the queue.

The following example will demonstrate how to pull messages from a configured RabbitMQ. A similar process will be involved for other message queues.

  1. From a Designer Project, create a new Flow.
  2. Navigate to the Properties panel for the Flow. Under the SETTINGS category, select the drop-down menu under Behavior Type and select Message Queue Handler Flow.

    Choosing this Flow behavior provides three additional Flow Inputs; Message, Handler Id, and Headers. The Message Input contains the Payload (Byte[]), Id (String), and MessageDateTime (DateTime) Inputs.
  3. From Toolbox, navigate to DATA > TEXT and attach a Get String From UTF 8 Bytes step to the Start step. 
  4. On the Properties panel under INPUTS, click Unknown and select Select From Flow. Click Message, select Payload, and click DONE. 
    RabbitMQ Messages are typically encoded in UTF8. Other messengers may use Base 64, Ascii, or a different UTF decoding step to help decode the Payload.

  5. Attach a Show Popup step from Toolbox > FAVORITE STEPS to the workspace. Map GetStringFromUTF8Bytes1_Output to Message, and Constant map the desired Subject

  6. Click Save to save changes to the Flow.

Subscribing to a Queue

The messaging system Queue will need to be configured in order for Decisions to subscribe to it.

  1. If a Queue has not been added, navigate to System > Jobs & Events > Message Queues. Click ADD RABBIT QUEUE from the Global Action Bar
  2. From the Add Rabbit Queue window, define the Message Queue parameters and click SAVE. 

Connect Processing Flow to Queue

The following demonstrates a Message Queue Handler. The setting options can be overridden to specify different servers or queues by navigating to System > Jobs and Events > Message Queues, creating a message queue, and selecting the Override Server Info option.

  1. Navigate to System > Jobs and Events > Message Queue Handlers. Click ADD MESSAGE HANDLER.
  2. From the Add Message Handler window, define the desired Handler Name, select the desired Message Handling behavior, define the Active Flow Count, create or pick the Message Handler Flow, then select the Message Queue. Click SAVE.  
Configuration OptionsDescription
Handler NameName to display in Decisions.
Message HandlingSets the Message Handling mode to lease the message (lock), lease the message temporarily (lock with auto timeout), remove it after processing (pop), or use it but leave it on the Queue (peek).


Receives a message from the queue. Decisions will send an acknowledgment to the queue once the message has completed processing.

Lease w/ Expire

Shares the same behavior as leased, with the addition of sending not acknowledged signals. There are two ways for messages can time out: The Message Handler Flow throws an exception or the communication between Decisions and the message server is broken.

GetRetrieves a message from the queue. The message will be processed, and no acknowledgment will be sent to the queue.

Get and RemoveRetrieves and removes a message from the queue without sending an acknowledgment.
Active Flow CountThe maximum number of simultaneous Messages that Decisions will process.
PICK HANDLER FLOWThe Flow is used to process Messages that appear in the Queue.
Message QueueThe Queue for the Handler to listen on was configured in System Settings.

For further information on Modules, visit the Decisions Forum.

Was this article helpful?