Tasks

Publish to Message Broker

Publishes a message to a RabbitMQ queue using either the AMQP or STOMP protocol.

# Use cases

• Push events from a stub onto a RabbitMQ queue for downstream consumers to process.
• Hand off long-running work to a worker that listens on a queue.
• Fan out notifications to other services or systems via a shared message broker.
• Integrate with RabbitMQ over the standard AMQP protocol or via STOMP / Web-STOMP (WebSocket).

# Basic usage

# Parameters

# destination

required

string

The queue or destination that the message will be published to.

• For AMQP, this is the queue name. The queue is asserted before publishing, so it will be created if it does not exist.
• For STOMP, this is a STOMP destination string. Common formats are /queue/{name}, /exchange/{name}/{routing-key}, /amq/queue/{name} and /topic/{pattern}.

# message

required

object

The message payload to publish. The object is serialised to JSON before being sent on the wire.

# rabbitmq

required

object

The RabbitMQ connection settings. The same rabbitmq object is used for both AMQP and STOMP — the protocol is either set explicitly or inferred from the connection URL.

# rabbitmq.protocol

optional

string

The protocol to use to connect to RabbitMQ. Must be either "amqp" or "stomp".

If not set, the protocol is inferred from the connecturl:

• amqp:// or amqps:// → amqp
• stomp://, ws:// or wss:// → stomp

If the protocol cannot be inferred and no value is supplied, it defaults to amqp.

# rabbitmq.connect_options

required

object

The connection details for RabbitMQ. You can either provide a full connecturl or supply the individual fields below and let the task build the URL for you.

# rabbitmq.connect_options.connecturl

optional

string

The full connection URL to RabbitMQ. When provided this takes priority over the individual host, port, username, password and vhost fields.

To ensure that your connection URL remains secret, use credentials.

# rabbitmq.connect_options.host

optional

string

The RabbitMQ host address. Required when connecturl is not provided.

# rabbitmq.connect_options.port

optional

number

The port to connect on.

Defaults:

• 5672 for AMQP
• 61613 for STOMP
• 15674 for Web-STOMP (when use_websocket is true)

# rabbitmq.connect_options.username

optional

string

The username used to authenticate against RabbitMQ.

• AMQP: required when connecturl is not provided.
• STOMP: optional. If both username and password are provided they are included in the generated URL; otherwise the URL is built without auth credentials.

# rabbitmq.connect_options.password

optional

string

The password used to authenticate against RabbitMQ.

• AMQP: required when connecturl is not provided.
• STOMP: optional, paired with username as described above.

# rabbitmq.connect_options.vhost

optional

string

The RabbitMQ virtual host.

Default: /

# rabbitmq.connect_options.use_websocket

optional

boolean

STOMP only. When true the task connects using Web-STOMP over a WebSocket instead of a raw STOMP TCP connection.

Default: false

# rabbitmq.connect_options.heartbeat

optional

string

STOMP only. The heart-beat intervals in milliseconds, as a comma-separated cx,cy string.

Default: "5000,5000"

# rabbitmq.connect_options.timeout

optional

number

STOMP only. The connection timeout in milliseconds.

Default: 5000

# message_options

optional

object

Optional message properties applied to the published message.

# message_options.persistent

optional

boolean

Controls message persistence.

• AMQP: when true (the default) the message is published as persistent and the queue is asserted as durable. Set to false to publish a transient message to a non-durable queue.
• STOMP: when explicitly set, a persistent header ("true" or "false") is included on the SEND frame. If omitted, no persistent header is sent and the broker's default behaviour applies.

# message_options.content_type

optional

string

The content type set on the published message.

Default: "application/json"

# message_options.priority

optional

number

The message priority. Valid range is 0–10.

# message_options.headers

optional

object

STOMP only. Custom headers to include on the STOMP SEND frame.

# org_credentials

optional

object

A map of credential keys to credential UUIDs. The values are resolved against the organization's Credentials and made available to targeted substitution inside the connecturl.

See Using credentials for the connection url for an example.

# Result

# Properties

publish_result.destination

The queue or destination that the message was published to.

publish_result.message_size

The size in bytes of the serialised message payload that was published.

publish_result.timestamp

An ISO 8601 timestamp recording when the message was published.

# Examples

# Publishing over AMQP

Publish a message to a RabbitMQ queue using the default AMQP protocol. Replace the connecturl with your own.

# Publishing over STOMP

Publish a message using the STOMP protocol. The protocol is inferred from the stomp:// URL scheme.

# Publishing over Web-STOMP (WebSocket)

Connect to RabbitMQ's Web-STOMP plugin over a WebSocket by setting use_websocket to true. The default port 15674 is used when port is not specified.

# Building the connection from individual fields

If you don't want to supply a full connecturl, provide host, username and password separately and the task will build the URL for you.

# Using credentials for the connection url

It is possible to use credentials to ensure that your connection URL remains secret and is not displayed in the task on your template.

Create a new Generic credential, set the credential name to whatever you would like and set the Secret Value to your connection URL.

After you create the credential, copy the credential UUID and structure the publish_to_message_broker task as follows:

The org_credentials object maps a key (used inside the substitution) to a Generic Credential UUID. The connecturl then uses targeted substitution to pull in the resolved credential value at runtime.