> 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/konsumenci-rabbitmq/konfiguracja.md).

# Configuration

This page describes the configuration that administrators prepare so that [the RabbitMQ consumer](https://docs.eximee.com/documentation/documentation-en/eksploatacja-aplikacji/obsluga-zdarzen/konsumenci-rabbitmq.md) receives messages. Messages from queues are received by the `lowcode-queue-consumer`. For each queue from its configuration, it registers a listener, and each message received from that queue is passed to the consumer assigned to it.

To configure it, you need the data that the process designer agreed with the administrators and sent in the request ([request example](https://docs.eximee.com/documentation/documentation-en/eksploatacja-aplikacji/obsluga-zdarzen/konsumenci-rabbitmq.md#przyklad-zgloszenia)): the queue name, consumer name, DLQ name, and connection name.

## Configuration example

You set all variables in the `env.yaml` file (ConfigMap) of the application `lowcode-queue-consumer`. Full configuration example with one connection and one queue:

```yaml
# Artifact repository: from it the application downloads consumer scripts
EXIMEE_REPOSITORY_USER: '<user>'
EXIMEE_REPOSITORY_PASSWORD: '<password>'

# Eximee BPMS: to it scripts send messages that resume processes
EXIMEE_ROUTER_ENGINE_USER: '<user>'
EXIMEE_ROUTER_ENGINE_PASSWORD: '<password>'

# RabbitMQ broker data, common for all connections
SCRIPT_QUEUE_COMMON_CONSUMER_CLIENT_HOST: 'rabbitmq.bank.local'
SCRIPT_QUEUE_COMMON_CONSUMER_CLIENT_PORT: '5671'
SCRIPT_QUEUE_COMMON_CONSUMER_CLIENT_SSL_ENABLED: 'true'
SCRIPT_QUEUE_COMMON_CONSUMER_CLIENT_SSL_VALIDATE_SERVER_CERTIFICATE: 'true'
SCRIPT_QUEUE_COMMON_CONSUMER_CLIENT_SSL_VERIFY_HOSTNAME: 'true'
SCRIPT_QUEUE_COMMON_CONSUMER_CLIENT_VIRTUAL_HOST: 'eximee'
SCRIPT_QUEUE_COMMON_CONSUMER_CLIENT_USERNAME: '<user>'
SCRIPT_QUEUE_COMMON_CONSUMER_CLIENT_PASSWORD: '<password>'

# "integration" connection: queue -> consumer and queue -> DLQ
SCRIPT_QUEUE_INTEGRATION_QUEUE_MAPPING: 'eximee_demo_integration=message_consumer_demo'
SCRIPT_QUEUE_INTEGRATION_QUEUE_DLQ_MAPPING: 'eximee_demo_integration=eximee_demo_integration.dlq'
```

The following sections describe where to get the values for this example, how to prepare the broker, and then the connections, segment `COMMON` and each variable.

## Data from the request

| Data from the request                      | What to do with them                                                                                                                                                                                                                                                                                                   |
| ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Connection name, for example `integration` | The process designer may suggest a name. Confirm it or point to an existing connection to which you will add the queue mapping. Use it in uppercase in variable names, for example `SCRIPT_QUEUE_INTEGRATION_QUEUE_MAPPING`. The name cannot contain the character `_` (section [Connection name](#nazwa-polaczenia)). |
| Queue                                      | Create the queue on the broker (section [Preparing the broker](#przygotowanie-brokera)) and enter it on the left side `QUEUE_MAPPING`.                                                                                                                                                                                 |
| Consumer name                              | Enter it on the right side `QUEUE_MAPPING`, for example `eximee_demo_integration=message_consumer_demo`. The name must be identical to the consumer name in Eximee Designer.                                                                                                                                           |
| DLQ queue                                  | Create the queue on the broker and enter it in `QUEUE_DLQ_MAPPING`, for example `eximee_demo_integration=eximee_demo_integration.dlq` (section [Error handling: DLX and DLQ](#obsluga-bledow-dlx-i-dlq)).                                                                                                              |

## Preparing the broker

The platform does not create queues, exchanges, or bindings on the broker. Before changing the Eximee configuration, the RabbitMQ administrator creates on the broker the queue from which the consumer is to read, and the DLQ queue. The way to prepare the DLQ is described in section [Error handling: DLX and DLQ](#obsluga-bledow-dlx-i-dlq).

{% hint style="danger" %}
The queue indicated in the mapping must exist on the broker before the application starts. The same applies to the queue indicated in the DLQ mapping. If either is missing, the application `lowcode-queue-consumer` will not start.
{% endhint %}

## Connections and segment `COMMON`

The configuration consists of named connections. A connection is broker data (address, virtual host, user, TLS) and queue-to-consumer mapping. For each connection, the application opens a separate connection to the broker.

`COMMON` is not a connection. It is a set of default values that the application adds to each connection. A connection can override any of them with its own value. A configuration that contains only the variables `COMMON`, does not create any connection and does not receive messages.

### Typical configuration: one broker

If all queues are on one broker, in one virtual host. Then:

* set the broker data once, in the variables `SCRIPT_QUEUE_COMMON_CONSUMER_CLIENT_*`,
* create one connection, for example `INTEGRATION`, and set only the queue mapping in it,
* add each next queue to the mapping of the same connection, separated by commas.

This is what the [configuration example](#przyklad-konfiguracji) at the top of the page looks like. With two queues, the connection mapping `INTEGRATION` looks like this:

```yaml
SCRIPT_QUEUE_INTEGRATION_QUEUE_MAPPING: 'eximee_demo_integration=message_consumer_demo,other_queue=other_consumer'
SCRIPT_QUEUE_INTEGRATION_QUEUE_DLQ_MAPPING: 'eximee_demo_integration=eximee_demo_integration.dlq,other_queue=other_queue.dlq'
```

One consumer can be assigned to several queues. One application instance processes messages from a given queue sequentially, one after another.

### Multiple connections: another broker, virtual host, or user

Add another connection when some of the queues are on a different broker, in a different virtual host, or require a different user. In the new connection, set only the data that differs from `COMMON`, and its own mapping.

Example: the partner queues are on the same broker, but in the virtual host `partner`. The connection `PARTNER` overrides the virtual host, and takes the address, port, TLS, and credentials from `COMMON`:

```yaml
SCRIPT_QUEUE_PARTNER_CONSUMER_CLIENT_VIRTUAL_HOST: 'partner'
SCRIPT_QUEUE_PARTNER_QUEUE_MAPPING: 'partner_queue=partner_consumer'
```

{% hint style="warning" %}
Do not set `QUEUE_MAPPING` or `QUEUE_DLQ_MAPPING` in the section `COMMON`. Mapping from `COMMON` applies to every connection, so each connection would look for the same queues on its own broker.
{% endhint %}

### Connection name

The connection name is the part of the variable name between `SCRIPT_QUEUE_` and `_QUEUE_MAPPING`. In the example `SCRIPT_QUEUE_INTEGRATION_QUEUE_MAPPING` the connection is called `INTEGRATION`, and in the application logs it appears as `integration`.

* The connection name is one word, without the character \_. `_`The application treats the character \_ in the variable name as a separator. From the variable `_` in the variable name as a separator. From the variable `SCRIPT_QUEUE_CENTRAL_BANK_QUEUE_MAPPING` no connection `CENTRAL_BANK`, and the listener will not be registered. Use for example `CENTRALBANK`.
* Name `COMMON` is reserved for default values and does not create a connection.

## Application variables `lowcode-queue-consumer`

### Artifact repository and Eximee BPMS

| Variable                        | Description                        | Default value                                  |
| ------------------------------- | ---------------------------------- | ---------------------------------------------- |
| `EXIMEE_REPOSITORY_URL`         | Artifact repository address.       | `http://eximee-repository:8080`                |
| `EXIMEE_REPOSITORY_USER`        | Artifact repository user.          | None (required)                                |
| `EXIMEE_REPOSITORY_PASSWORD`    | Artifact repository user password. | None (required)                                |
| `EXIMEE_ROUTER_ENGINE_URL`      | Eximee BPMS API address.           | `http://eximee-router-engine:8080/engine-rest` |
| `EXIMEE_ROUTER_ENGINE_USER`     | Eximee BPMS user.                  | None (required)                                |
| `EXIMEE_ROUTER_ENGINE_PASSWORD` | Eximee BPMS user password.         | None (required)                                |

### Broker connection

Instead of `<POLACZENIE>` enter `COMMON` (value for all connections) or the connection name (value only for it). The default value applies when the variable is not set either for the connection or in `COMMON`.

| Variable                                                                    | Description                                                                                                                      | Default value                             |
| --------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
| `SCRIPT_QUEUE_<POLACZENIE>_CONSUMER_CLIENT_HOST`                            | Broker address.                                                                                                                  | `localhost`                               |
| `SCRIPT_QUEUE_<POLACZENIE>_CONSUMER_CLIENT_PORT`                            | Broker port.                                                                                                                     | `5671` with TLS enabled, otherwise `5672` |
| `SCRIPT_QUEUE_<POLACZENIE>_CONSUMER_CLIENT_VIRTUAL_HOST`                    | RabbitMQ virtual host.                                                                                                           | `/`                                       |
| `SCRIPT_QUEUE_<POLACZENIE>_CONSUMER_CLIENT_USERNAME`                        | Broker user.                                                                                                                     | `guest`                                   |
| `SCRIPT_QUEUE_<POLACZENIE>_CONSUMER_CLIENT_PASSWORD`                        | Broker user password.                                                                                                            | `guest`                                   |
| `SCRIPT_QUEUE_<POLACZENIE>_CONSUMER_CLIENT_SSL_ENABLED`                     | `true` enables connection encryption (TLS).                                                                                      | `false`                                   |
| `SCRIPT_QUEUE_<POLACZENIE>_CONSUMER_CLIENT_SSL_VALIDATE_SERVER_CERTIFICATE` | `true` enables broker certificate verification. Description in section [Encrypted connection (TLS)](#polaczenie-szyfrowane-tls). | `false`                                   |
| `SCRIPT_QUEUE_<POLACZENIE>_CONSUMER_CLIENT_SSL_VERIFY_HOSTNAME`             | `true` enables checking whether the broker certificate was issued for its address.                                               | `false`                                   |

{% hint style="info" %}
Reception variables have `CONSUMER`in their name. The send variables from scripts, with `PRODUCER` in their name, are configured separately in applications that run the scripts (page [Sending to RabbitMQ configuration](https://docs.eximee.com/documentation/documentation-en/eksploatacja-aplikacji/obsluga-zdarzen/lowcode-do-rabbitmq/konfiguracja.md)).
{% endhint %}

### Queue mapping

Instead of `<POLACZENIE>` enter the connection name here. Do not set these variables in `COMMON`.

| Variable                                      | Description                                                                                                                                                                                                                                        | Default value                                                  |
| --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
| `SCRIPT_QUEUE_<POLACZENIE>_QUEUE_MAPPING`     | Queue-to-consumer mapping in the form `<queue-name>=<consumer-name>`. Separate multiple pairs with commas.                                                                                                                                         | None: a connection without mapping does not receive messages   |
| `SCRIPT_QUEUE_<POLACZENIE>_QUEUE_DLQ_MAPPING` | Queue-to-DLQ mapping in the form `<queue-name>=<dlq-queue-name>`. Separate multiple pairs with commas. On the left side, only a queue that appears in `QUEUE_MAPPING` of the same connection may stand. Otherwise, the application will not start. | None: the queue's DLX determines the fate of rejected messages |

### Consumer cache

| Variable                                   | Description                                                                                  | Default value |
| ------------------------------------------ | -------------------------------------------------------------------------------------------- | ------------- |
| `LOWCODE_QUEUE_CONSUMER_FETCH_CACHE_TTL`   | How long the application stores the consumer fetched from the repository, for example `30s`. | `1s`          |
| `LOWCODE_QUEUE_CONSUMER_COMPILE_CACHE_TTL` | How long the application stores the compiled consumer script, for example `30s`.             | `1s`          |

The change to the consumer saved in Eximee Designer takes effect after these TTLs expire. You can also clear the cache immediately:

```bash
curl -X POST https://DOCKER_HOST:PORT/lowcode-queue-consumer/cache/invalidate
```

{% hint style="warning" %}
The application ignores a variable with a typo in its name without warning, for example `SSL_ENABLE` instead of `SSL_ENABLED`. After each configuration change, check in the logs whether the application registered listeners on the correct queues (description in section [Verification](#sprawdzenie-dzialania)).
{% endhint %}

## Encrypted connection (TLS)

For an encrypted connection with broker certificate verification, set all three variables:

```yaml
SCRIPT_QUEUE_COMMON_CONSUMER_CLIENT_SSL_ENABLED: 'true'
SCRIPT_QUEUE_COMMON_CONSUMER_CLIENT_SSL_VALIDATE_SERVER_CERTIFICATE: 'true'
SCRIPT_QUEUE_COMMON_CONSUMER_CLIENT_SSL_VERIFY_HOSTNAME: 'true'
```

The broker certificate is then checked by the default Java truststore in the application image. A self-signed certificate or one issued by an internal CA will be rejected if that CA is not in the truststore.

{% hint style="danger" %}
Only `SSL_ENABLED: 'true'` encrypts the connection, but does not verify the broker certificate: the application will accept any certificate. In production environments, always set `SSL_VALIDATE_SERVER_CERTIFICATE` and `SSL_VERIFY_HOSTNAME`.
{% endhint %}

## Error handling: DLX and DLQ

A message that the consumer did not process (the script threw an exception) is rejected and does not return to the queue. The further path of such a message is determined by one of two variants described below. Choose one variant for each queue.

* **DLQ** (Dead Letter Queue) is a queue where rejected messages wait for analysis.
* **DLX** (Dead Letter Exchange) is an exchange to which the broker forwards messages rejected from the queue.

{% hint style="danger" %}
If none of the variants is configured for a queue, rejected messages are lost. The platform does not store them anywhere else, so they cannot be restored or analyzed.
{% endhint %}

### Variant A: DLQ indicated in the Eximee configuration (recommended)

The RabbitMQ administrator creates a regular DLQ queue, for example `eximee_demo_integration.dlq`. The Eximee administrator indicates it in the variable `QUEUE_DLQ_MAPPING`:

```yaml
SCRIPT_QUEUE_INTEGRATION_QUEUE_DLQ_MAPPING: 'eximee_demo_integration=eximee_demo_integration.dlq'
```

The application publishes the unprocessed message to this queue with unchanged content and headers. It adds three headers helpful for analysis:

| Header                  | Content                                                                                                                                                                                                                                                                    |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `x-original-exchange`   | The exchange from which the message reached the queue. Empty for the default exchange.                                                                                                                                                                                     |
| `x-original-routingKey` | The routing key with which the message reached the queue.                                                                                                                                                                                                                  |
| `x-exception-class`     | The type of error, for example `com.consdata.eximee.script.runtime.api.ScriptRuntimeException`, when the script threw an exception, or `com.consdata.eximee.lowcode.core.exception.ScriptCodeNotFoundException`, when there is no consumer with the name from the mapping. |

The error content does not get into the message. You can find the error details in the application logs `lowcode-queue-consumer`.

Variant A has priority: for a queue with an entry in `QUEUE_DLQ_MAPPING` the application does not use the DLX set on the queue.

### Variant B: DLX set on the queue by the RabbitMQ administrator

The RabbitMQ administrator sets queue arguments that point to the DLX and binds the DLQ queue to that exchange. Example for the queue `eximee_demo_integration`:

```
Queue eximee_demo_integration, arguments:
  x-dead-letter-exchange:    eximee_demo_integration.dlx
  x-dead-letter-routing-key: eximee_demo_integration.dlq

Exchange eximee_demo_integration.dlx, direct type

Queue eximee_demo_integration.dlq,
  binding from exchange eximee_demo_integration.dlx
  with routing key eximee_demo_integration.dlq
```

In this variant, you do not set `QUEUE_DLQ_MAPPING`. The broker adds the header `x-death` with the source queue name and the reason `rejected`.

### Messages in the DLQ

A message from the DLQ is not automatically processed again. The administrator should analyze the cause of the error and decide on further action, for example, after fixing the script, move the message back to the source queue using RabbitMQ tools.

## Deploying configuration changes

The application reads the configuration at startup. After changing `env.yaml`, for example after adding a new queue, start the application `lowcode-queue-consumer` again.

## Verification

1. After the application starts `lowcode-queue-consumer` find in its logs an entry for each mapped queue:

   ```
   Registering queue listener. [connectionId=integration, queue=eximee_demo_integration, script=message_consumer_demo, deadLetterQueue=eximee_demo_integration.dlq]
   ```

   Value `deadLetterQueue=the queue's dead-letter exchange` means that for the queue no `QUEUE_DLQ_MAPPING` is set and the fate of rejected messages is determined by the queue's DLX (variant B).
2. Check the status of broker connections in monitoring (e.g. Grafana).
3. In the RabbitMQ Management panel, open the queue, expand the **Publish message** and publish a test message in the agreed format, with the process instance identifier waiting at the wait step. The message format is agreed upon by the process designer with the external system team.
4. In the application logs, find the entry about receiving the message:

   ```
   Message received [connectionId=integration, stream=eximee_demo_integration, script=message_consumer_demo, ...]
   ```

   and then the entries from `Logger` in the consumer script.
5. Check whether the process moved on and whether the DLQ is empty.

## Troubleshooting

| Symptom                                                                                                           | Possible cause                                                                                                                                                                                                                                                                   | Solution                                                                                                                                    |
| ----------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| Application `lowcode-queue-consumer` does not start, in the log `Queue <name> does not exist on the broker`       | Queue with `QUEUE_MAPPING` or `QUEUE_DLQ_MAPPING` does not exist on the broker. The log shows the queue and the variable in which it was entered.                                                                                                                                | Create the queue on the broker or correct the name in the mapping.                                                                          |
| Application does not start, in the log `is not mapped to a script`                                                | `QUEUE_DLQ_MAPPING` contains a queue that is not in `QUEUE_MAPPING` the same connection.                                                                                                                                                                                         | Add the queue to `QUEUE_MAPPING` or remove it from `QUEUE_DLQ_MAPPING`.                                                                     |
| Messages stay on the queue, in the log there is no `Registering queue listener` for this queue                    | No mapping, typo in variable name, or character `_` in the connection name.                                                                                                                                                                                                      | Correct the variable name according to the section [Connection name](#nazwa-polaczenia) and restart the application.                        |
| Application does not start, in the log `AmqpConnectException`, `AmqpAuthenticationException` or `AmqpIOException` | The application connects to the broker at startup. `AmqpConnectException`: the broker is unavailable or the address or port is incorrect. `AmqpAuthenticationException`: incorrect login details. `AmqpIOException` with `vhost ... not found`: the virtual host does not exist. | Check the variables `CONSUMER_CLIENT_*` and broker availability from the application. On port `5671` check whether it is set `SSL_ENABLED`. |
| Each message goes to the DLQ with `x-exception-class` = `...ScriptCodeNotFoundException`                          | The consumer name in `QUEUE_MAPPING` differs from the name in Eximee Designer.                                                                                                                                                                                                   | Correct the name in the mapping.                                                                                                            |
| The error message disappears and is not in any queue                                                              | No DLQ or DLX has been configured for the queue.                                                                                                                                                                                                                                 | Configure the DLQ according to the section [Error handling: DLX and DLQ](#obsluga-bledow-dlx-i-dlq).                                        |

## Related pages

* [RabbitMQ consumers](https://docs.eximee.com/documentation/documentation-en/eksploatacja-aplikacji/obsluga-zdarzen/konsumenci-rabbitmq.md) — process preparation and writing the consumer.
* [Low-code for RabbitMQ](https://docs.eximee.com/documentation/documentation-en/eksploatacja-aplikacji/obsluga-zdarzen/lowcode-do-rabbitmq.md) — sending messages to the queue from scripts and script tasks.


---

# 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/konsumenci-rabbitmq/konfiguracja.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.
