> For the complete documentation index, see [llms.txt](https://docs.eximee.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.eximee.com/documentation/documentation-en/eksploatacja-aplikacji/obsluga-zdarzen/lowcode-do-rabbitmq.md).

# Low-code for RabbitMQ

{% hint style="info" %}
The availability of this functionality depends on the license and may not be available in all deployments.
{% endhint %}

## Purpose

Enable sending messages to a specified RabbitMQ queue directly from requests (scripts) and BPMN processes (script tasks).

## Usage examples

* Sending a request to an external system, with the response returned asynchronously (see [RabbitMQ consumers](https://docs.eximee.com/documentation/documentation-en/eksploatacja-aplikacji/obsluga-zdarzen/konsumenci-rabbitmq.md))
* Notifying external systems about process status changes
* Communication with external systems (e.g. bank systems)

## How it works

```
1. The script calls api.queue.v1.publishAsync with the connection name, routing key,
                           message body and headers
2. The Eximee application converts the body to JSON and publishes the message to the exchange
                           configured for this connection, with the given routing key
3. The RabbitMQ broker routes the message to queues that have an exchange binding with this routing key
```

The broker connection and exchange are configured by the administrator in the application settings. The script only specifies the connection name and routing key.

## Step 1. Determine the details with the administrators

Before writing the script, determine with the administrators:

* **the connection name**, through which the script sends messages, for example `integration`. The process designer can suggest a name, and the administrators confirm it or indicate an existing connection. The name is one word, without the character `_`,
* **where the message should go**, i.e. the exchange and routing key. These two values are determined together, because the exchange determines what the routing key is:
  * for the default exchange (an empty exchange name in the configuration), the routing key is the name of the target queue, so it is enough to determine the queue,
  * for a custom exchange, determine its name and routing key. Which queue the message will go to is decided by the bindings defined on the broker,
* **where you send messages from**: from a service script in a form, from a script task in a process, or from both. This determines in which applications the administrators configure the connection.

In the examples on this page, messages are sent through the connection `integration` with the default exchange to the queue `eximee_demo_integration`. Messages are consumed from this queue by the consumer described on the page [RabbitMQ consumers](https://docs.eximee.com/documentation/documentation-en/eksploatacja-aplikacji/obsluga-zdarzen/konsumenci-rabbitmq.md).

### Request example

Send the agreed details to the administrators in the request, for example:

```
Request to configure sending to RabbitMQ:
- connection name: integration
- exchange: default
- target queue (routing key): eximee_demo_integration
- send from: service script in a form, script task in a process
```

The configuration that the administrators prepare on this basis is described on the page [RabbitMQ sending configuration](https://docs.eximee.com/documentation/documentation-en/eksploatacja-aplikacji/obsluga-zdarzen/lowcode-do-rabbitmq/konfiguracja.md).

## Step 2. Send a message from the script

```js
api.queue.v1.publishAsync(
    'integration',                    // connection name from step 1, in lowercase
    'eximee_demo_integration',        // routing key from step 1: for the default exchange, the queue name
    {                                 // message body: object converted to JSON
        processInstanceId: '123',
        data: 'sample value'
    },
    {                                 // headers: text values; if none, provide {}
        header1: 'header1-value'
    }
);
```

| Parameter       | Description                                                                                                                                                 | Where to get the value from                           |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| connection name | The connection name from the application configuration, written in lowercase. Case matters: `'INTEGRATION'` instead of `'integration'` results in an error. | Name agreed with the administrators in step 1.        |
| routing key     | The message routing key. For the default exchange, it is the name of the target queue.                                                                      | Routing key agreed with the administrators in step 1. |
| body            | The value that the function converts to JSON (`JSON.stringify`). Description in the section [Message body and headers](#tresc-i-naglowki-wiadomosci).       | You determine it with the message recipient.          |
| headers         | Object with message headers. The parameter is required: if you are not sending headers, provide `{}`.                                                       | You determine it with the message recipient.          |

The function returns after passing the message to the broker. It does not wait for confirmation that the broker accepted the message or that the recipient processed it.

### Sample service script

The service script reads the parameters `processInstanceId` and `data`, builds the message and sends it to the queue `eximee_demo_integration`:

```js
function callService(context) {
    const CONNECTION_ID = 'integration';
    const ROUTING_KEY = 'eximee_demo_integration';

    const processInstanceId = context.getFirstParameter('processInstanceId');
    const data = context.getFirstParameter('data');

    if (!processInstanceId) {
        Logger.error('Rabbit demo message not published, processInstanceId is empty');
        return [{'published': 'false'}];
    }

    const payload = {
        processInstanceId: String(processInstanceId),
        data: (data === undefined || data === null) ? '' : String(data)
    };

    api.queue.v1.publishAsync(CONNECTION_ID, ROUTING_KEY, payload, {});
    Logger.info('Rabbit demo message published [routingKey={}, processInstanceId={}]',
        nonsensitive(ROUTING_KEY), nonsensitive(processInstanceId));

    return [{'published': 'true'}];
}
```

For the parameters `processInstanceId` = `8f0b7a52-0c43-11ef-9a1c-0242ac120002` and `data` = `sample value` to the queue `eximee_demo_integration` the message goes:

```json
{"processInstanceId":"8f0b7a52-0c43-11ef-9a1c-0242ac120002","data":"sample value"}
```

### Sample script task

The script task sends a message with the process instance ID. If sending fails, it raises an incident on the task, so the process stops until intervention:

```js
function handle(task, context) {
    try {
        api.queue.v1.publishAsync('integration', 'eximee_demo_integration', {
            processInstanceId: task.getProcessInstanceId(),
            data: task.getVariable('data')
        }, {});
    } catch (e) {
        context.handleFailure('Failed to send message to RabbitMQ: ' + e.message);
        return;
    }
    context.complete({});
}
```

More about script tasks: [Script Tasks API](https://docs.eximee.com/documentation/documentation-en/budowanie-aplikacji/logika-biznesowa/scriptcode/zadanie-skryptowe-scripttask/api-zadan-skryptowych.md).

## Message body and headers

The function always converts the body to JSON using `JSON.stringify`. The message is sent with content type `application/json`, encoding `UTF-8` and as persistent.

| Passed body                             | Message body on the queue                                             |
| --------------------------------------- | --------------------------------------------------------------------- |
| `{processInstanceId: '123', data: 'x'}` | `{"processInstanceId":"123","data":"x"}`                              |
| `{d: new Date(0)}`                      | `{"d":"1970-01-01T00:00:00.000Z"}`: data as text in the UTC time zone |
| `'abc'`                                 | `"abc"`: text in quotes                                               |
| `JSON.stringify({a: 1})`                | `"{\"a\":1}"`: JSON encoded a second time                             |
| `null`                                  | `null`                                                                |
| `undefined`                             | `undefined`: a body that is not valid JSON                            |

{% hint style="warning" %}
Pass the body as an object. Do not convert it to text yourself using the function `JSON.stringify`: the recipient will then receive text in quotes instead of a JSON object.
{% endhint %}

Headers:

* Header values must be text. A number or boolean value will cause an error; convert it using the function `String()`.
* Header with a value `null` is omitted.
* The message has no identifier set (`message_id`) or timestamp (`timestamp`). If the recipient needs them, pass them in the body or headers.

## Error handling

The function raises an error that you can catch in a `try/catch`block, when:

| Situation                                                                                                       | Error message                                        |
| --------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| No connection with the specified name is configured in the application, or the name has different letter casing | `No queue client found. [connectionId=<name>]`       |
| The broker is unavailable                                                                                       | `org.springframework.amqp.AmqpConnectException: ...` |
| The header value is not text                                                                                    | `ClassCastException`                                 |
| Missing headers parameter                                                                                       | `Can't find method ... publishAsync(...)`            |

{% hint style="danger" %}
The function does not raise an error when the broker cannot deliver the message: for a routing key for which there is no queue, and for an exchange that does not exist on the broker. The message is lost without trace. Before running, check the connection name, routing key, and bindings on the broker with the administrators, and after the first send, check whether the message reached the queue.
{% endhint %}

## Troubleshooting

| Symptom                                                                   | Possible cause                                                                                                                                                          | Solution                                                                                                                                                                                                                                              |
| ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Error `No queue client found. [connectionId=...]`                         | The connection name in the script differs from the configuration, is written in uppercase, or the connection is not configured in the application that runs the script. | Use the lowercase name. Ask the administrators to check the configuration (page [RabbitMQ sending configuration](https://docs.eximee.com/documentation/documentation-en/eksploatacja-aplikacji/obsluga-zdarzen/lowcode-do-rabbitmq/konfiguracja.md)). |
| The script finishes without an error, but the message is not on the queue | Incorrect routing key, no binding with the queue, or an exchange that does not exist on the broker.                                                                     | Check the routing key and bindings on the broker with the administrators.                                                                                                                                                                             |
| The recipient gets text in quotes instead of a JSON object                | The body was converted to text before calling the function.                                                                                                             | Pass the body as an object.                                                                                                                                                                                                                           |
| Error `ClassCastException`                                                | The header value is not text.                                                                                                                                           | Convert the value using the function `String()`.                                                                                                                                                                                                      |

## Related pages

* [RabbitMQ sending configuration](https://docs.eximee.com/documentation/documentation-en/eksploatacja-aplikacji/obsluga-zdarzen/lowcode-do-rabbitmq/konfiguracja.md) — connection configuration in applications that run scripts.
* [RabbitMQ consumers](https://docs.eximee.com/documentation/documentation-en/eksploatacja-aplikacji/obsluga-zdarzen/konsumenci-rabbitmq.md) — receiving messages from the queue and resuming the process.
* [Script Tasks API](https://docs.eximee.com/documentation/documentation-en/budowanie-aplikacji/logika-biznesowa/scriptcode/zadanie-skryptowe-scripttask/api-zadan-skryptowych.md) — writing script tasks in a process.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.eximee.com/documentation/documentation-en/eksploatacja-aplikacji/obsluga-zdarzen/lowcode-do-rabbitmq.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
