Skip to main content
Skip table of contents

Messaging Basics

To be fully productive with developing flows, you will need a basic understanding of messaging because Flow Director sits on top of the SwiftMQ messaging system and uses it as runtime. This chapter will give you an introduction to messaging.


Flow Director uses Java Message Service (JMS) messages to transfer data. JMS defines 5 types of messages which only differ from the payload (message body):

  • TextMessage (string body)

  • BytesMessage (byte body)

  • MapMessage (key/value body)

  • StreamMessage (stream of data body)

  • ObjectMessage (Java object body)

  • Message (no body)

A flow mostly uses TextMessage, BytesMessage, and Message. In rare cases, it uses MapMessage. We can ignore Stream/ObjectMessage.

Message Properties

You can annotate JMS messages with message properties. In JMS, they are intended to select messages using a JMS selector, which is actually the WHERE clause of a SQL SELECT statement.


oderno between 1000 and 2000 and customerid = 33 and ordervalue > 10000

Flow Director, however, uses message properties to transfer the actual data. The message body is only used to parse data out of it, i.e., from a JSON body, and store it into the message properties. Or to use the data in the message properties to create a result and store it into a message body.

But for the processing of a message flow, the data has to be in the message properties to handle it like a row in a database:

Message Header

A JMS message also contains a message header where system information is stored. Only 2 headers are of interest in a flow:

  • ReplyTo

  • CorrelationId

ReplyTo contains the address of a requestor in a request/reply scenario. If a flow accepts requests and produces a result, it needs to know where to send the reply.

The requestor may send many requests and need some id to assign incoming replies to the original request. That’s where the CorrelationId is used for. The requestor sets it to a unique id, and the processing flow sets the same id in the reply.

JMS Destinations

The source and target of messages are called destinations in JMS. There are 2 types of destinations you need to understand: Queues and topics. Both destinations store and deliver their messages in a first-in, first-out manner (FIFO).


Exactly one consumer will receive a single message. If there are no consumers available when the message is sent, the queue will keep it until a consumer can process the message. A queue can have many consumers with messages load balanced across the available consumers.

A queue is physically located at a specific SwiftMQ router. Only flows deployed on that router can consume messages from the queue. Flows on any router can send messages to the queue by appending the router name to the queue name, i.e., instead of testqueue for a local queue, use testqueue@routerxyz to send to a remote queue.

Queues can be regular or temporary. A regular queue is automatically stored in a SwiftMQ router configuration, survives restarts, and must be explicitly destroyed when it is not needed anymore. It can store persistent and non-persistent messages. A temporary queue has a lifetime of the flow that created it and is destroyed when the flow is deactivated. It stores messages non-persistent, even if they are marked as persistent.


A topic implements publish and subscribe semantics. When you publish a message, it goes to all the interested subscribers - so zero to many subscribers will receive a copy of the message. Only subscribers who had an active subscription when the SwiftMQ router receives the message will get a copy of the message.

A flow can create a durable subscriber on a topic to receive messages while it is deactivated. A regular queue backs a durable subscriber. Temporary queues are backing non-durable subscribers.

Topics exist network-wide and are automatically created on the first use; they are not bound to a specific SwiftMQ router. You can send and receive messages from any router of the network.

The name of a topic can be hierarchical, as documented here.

Message Persistence

A producer can mark a message as persistent before sending it. The message is then written into a persistent store if sent to a regular queue and deleted from the store after the message has been consumed. If the message is sent to a topic, it is only written to disk if durable subscribers are receiving it. Persistent is the default. Non-persistent messages are never written to disk.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.