For the complete documentation index, see llms.txt. This page is also available as Markdown.

Configuration

This page describes the configuration that administrators prepare so that the RabbitMQ consumer 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): 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:

# 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).

Queue

Create the queue on the broker (section Preparing the broker) 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).

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.

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 at the top of the page looks like. With two queues, the connection mapping INTEGRATION looks like this:

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:

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).

false

SCRIPT_QUEUE_<POLACZENIE>_CONSUMER_CLIENT_SSL_VERIFY_HOSTNAME

true enables checking whether the broker certificate was issued for its address.

false

Reception variables have CONSUMERin 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).

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:

Encrypted connection (TLS)

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

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.

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.

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:

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:

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:

    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:

    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 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.

Last updated

Was this helpful?