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
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 variableSCRIPT_QUEUE_CENTRAL_BANK_QUEUE_MAPPINGno connectionCENTRAL_BANK, and the listener will not be registered. Use for exampleCENTRALBANK.Name
COMMONis reserved for default values and does not create a connection.
Application variables lowcode-queue-consumer
Artifact repository and Eximee BPMS
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.
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
Queue mapping
Instead of <POLACZENIE> enter the connection name here. Do not set these variables in COMMON.
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
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.
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:
The application publishes the unprocessed message to this queue with unchanged content and headers. It adds three headers helpful for analysis:
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
After the application starts
lowcode-queue-consumerfind in its logs an entry for each mapped queue:Value
deadLetterQueue=the queue's dead-letter exchangemeans that for the queue noQUEUE_DLQ_MAPPINGis set and the fate of rejected messages is determined by the queue's DLX (variant B).Check the status of broker connections in monitoring (e.g. Grafana).
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.
In the application logs, find the entry about receiving the message:
and then the entries from
Loggerin the consumer script.Check whether the process moved on and whether the DLQ is empty.
Troubleshooting
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.
Related pages
RabbitMQ consumers — process preparation and writing the consumer.
Low-code for RabbitMQ — sending messages to the queue from scripts and script tasks.
Last updated
Was this helpful?
