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

# Kafka Consumers

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

## Purpose

Processes in Eximee may consist of steps that require asynchronous communication with external systems. For example: we send a request to verify documents, but this is time-consuming, so we will have to wait for a response. This task can be performed asynchronously in an external system, and it can notify the Eximee process via Kafka. Kafka consumers are used precisely to handle such responses. We use them to receive the message, pre-process the data contained in it, and notify Eximee BPMS to continue the process execution.

## Mapping a Kafka topic to a Kafka Consumer

Every Kafka consumer must be linked to the topic it will listen to. To define such a mapping, we need:

* the topic name - we should receive it from above,
* the Kafka consumer name - we define it ourselves, analogously to the names of other artifacts,
* having both names, we can submit a request to the administrators to add a topic-to-Kafka-consumer mapping to the configuration (providing both names). Without the mapping, we will be able to write the Kafka consumer, but it will not receive messages.

## Kafka Consumers in a Process

Kafka consumers can operate independently, but they are usually linked to a process in Eximee BPMS. Kafka consumers in a process participate in events of the "Message" type. At a step of this type, Eximee BPMS waits for a message so it can continue the process execution. The message can be sent from a Kafka consumer.

![Figure 1. Example process with a step of type "Message Intermediate Catch Event" (event "Wait for notification from the bank")](/files/278efdcc9d287926352a9028582dfc261006d147)

During the process design stage, we must remember to fill in the message name in the configuration. It must meet the Eximee BPMS limitations ([Message Events](https://docs.eximeebpms.org/manual/latest/reference/bpmn20/events/message-events/)) and we will need it later when linking the process step to the Kafka consumer.

![Figure 2. Example configuration of a step of type "Message Intermediate Catch Event"](/files/f1720091799dc188918df6cf0ad900deca71b3ae)

## Creating a Kafka Consumer

In Eximee Designer, we select appropriately **Library** → **Kafka Consumers**. Here, like with the other artifacts, there is a button **Add Kafka Consumer**:

![Figure 3. Tab with artifact type: Kafka Consumers](/files/e31d8bfd4561e425c8bd816869ee529110019dc7)

{% hint style="info" %}
Kafka consumers have limited access to the API and can use only the functions available in `api.process.*`. More information about the API: [Process data operations and access](/documentation/documentation-en/budowanie-aplikacji/logika-biznesowa/scriptcode/skrypty-scriptservice/api-skryptow/operacje-i-dostep-do-danych-procesu.md)
{% endhint %}

Example of using a Kafka consumer:

```javascript
function callService(context) {
    // retrieve message content from the context
    var message = context.getMessage().value;
    // process the message
    var jsonValue = JSON.parse(stringValue);
    var processInstanceId = jsonValue.processInstanceId;
    // send a message to Eximee BPMS with information to continue the process
    api.process.v1.byInstanceId(messageValue.processInstanceId).correlateMessage('get-notification', null);
    return;
}
```

{% hint style="info" %}
The message format is not imposed, so the structure and type of data it contains should be defined upfront in order to be able to process it correctly.
{% endhint %}

When writing a Kafka consumer, we will almost always start by retrieving the message content using `context.getMessage().value;`. How we can process the message later depends on the defined message format, so the set and type of fields may be different in each case. It is important to remember the process instance identifier during the agreement stage. In the example, this is the processInstanceId field. Thanks to this value, we know which process instance the given message concerns.

## Retrieving data from a message

Using `context.getMessage()` we retrieve the message and its metadata. The object returned by this function has the following fields:

| Name        | Type     | Description                                                   |
| ----------- | -------- | ------------------------------------------------------------- |
| `value`     | `string` | The message content (payload).                                |
| `headers`   | `object` | Kafka message headers as a key-value map                      |
| `key`       | `string` | Kafka message key. It can be null if not provided.            |
| `topic`     | `string` | The name of the Kafka topic from which the message originates |
| `partition` | `number` | The topic partition number from which the message originates  |
| `offset`    | `number` | Timestamp (epoch ms) of message creation                      |
| `timestamp` | `number` | Message creation time                                         |

It should be noted that:

* `context.getMessage()` - retrieves the entire message object along with metadata,
* `context.getMessage().value` - retrieves only the message content. We will most often use this form.


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.eximee.com/documentation/documentation-en/eksploatacja-aplikacji/obsluga-zdarzen/konsumenci-kafka.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.