> 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/eksploatacja-aplikacji/obsluga-zdarzen/konsumenci-rabbitmq.md).

# Konsumenci RabbitMQ

{% hint style="info" %}
Dostępność funkcjonalności zależy od licencji i może nie być dostępna we wszystkich wdrożeniach.
{% endhint %}

## Cel

Procesy w Eximee mogą składać się z kroków, które wymagają asynchronicznej komunikacji z systemami zewnętrznymi. Przykład: wysyłamy żądanie o weryfikację dokumentów, jednak ta jest czasochłonna, więc na odpowiedź będziemy musieli poczekać. Zadanie to może być wykonane asynchronicznie w zewnętrznym systemie i może on powiadomić proces Eximee za pośrednictwem kolejki RabbitMQ. Konsumenci RabbitMQ służą właśnie do obsługi takich odpowiedzi. Używamy ich do odebrania wiadomości, wstępnego przetworzenia zawartych w niej danych oraz powiadamiania Eximee BPMS, by kontynuować wykonywanie procesu.

## Jak to działa

Cała ścieżka składa się z czterech elementów:

```
1. Proces Eximee           wysyła żądanie do systemu zewnętrznego, a w nim identyfikator instancji procesu,
                           i zatrzymuje się na kroku "Message Intermediate Catch Event"
                           
2. System zewnętrzny       wykonuje pracę i publikuje odpowiedź na kolejkę RabbitMQ,
                           odsyłając w niej identyfikator instancji procesu
                           
3. lowcode-queue-consumer  odbiera wiadomość z kolejki i uruchamia skrypt konsumenta
                           przypisanego do tej kolejki
                           
4. Skrypt konsumenta       odczytuje identyfikator instancji procesu i wysyła do Eximee BPMS
                           wiadomość, która wznawia proces
```

Odbiorem wiadomości zajmuje się aplikacja `lowcode-queue-consumer`. Aplikacja wie, który konsument obsługuje którą kolejkę, dzięki mapowaniu ustawionemu przez administratora w jej konfiguracji. Konsument sam w sobie nie zawiera informacji o kolejce.

## Krok 1. Ustal dane z administratorami

Przed przygotowaniem procesu ustal z administratorami:

* **kolejkę**, z której konsument ma odbierać wiadomości. Kolejkę zakłada na brokerze administrator RabbitMQ,
* **kolejkę DLQ**, na którą trafią wiadomości, których konsument nie przetworzy,
* **nazwę połączenia** z brokerem, w którym administratorzy skonfigurują kolejkę, na przykład `integration`. Projektant procesu może zaproponować nazwę, a administratorzy ją potwierdzają albo wskazują istniejące połączenie. Skrypt konsumenta nie używa tej nazwy, potrzebują jej administratorzy do konfiguracji,
* **nazwę konsumenta**, na przykład `message_consumer_demo`. Nazwę wybiera projektant procesu, a administratorzy wpisują ją w mapowaniu kolejki na konsumenta.

Bez mapowania kolejki na konsumenta konsument nie odbiera żadnych wiadomości.

### Przykład zgłoszenia

Ustalone dane wyślij administratorom w zgłoszeniu, na przykład:

```
Prośba o konfigurację konsumenta RabbitMQ w aplikacji lowcode-queue-consumer:
- kolejka: eximee_demo_integration
- konsument: message_consumer_demo
- DLQ: eximee_demo_integration.dlq
- połączenie: integration
```

Konfigurację, którą na tej podstawie przygotowują administratorzy, opisuje strona [Konfiguracja konsumentów RabbitMQ](https://docs.eximee.com/eksploatacja-aplikacji/obsluga-zdarzen/konsumenci-rabbitmq/konfiguracja.md).

{% hint style="warning" %}
Zapisz konsumenta w Eximee Designer, zanim na kolejkę zaczną trafiać wiadomości. Wiadomość, która przyjdzie, gdy konsumenta o nazwie z mapowania jeszcze nie ma, trafi do DLQ.
{% endhint %}

## Krok 2. Przygotuj proces

### Dodaj krok oczekiwania na wiadomość

W miejscu, w którym proces ma czekać na odpowiedź, dodaj krok typu **Message Intermediate Catch Event**. W panelu kroku rozwiń sekcję **Message** i w polu **Name** wpisz nazwę wiadomości. Nazwa musi spełniać wymagania Eximee BPMS ([Message Events](https://docs.eximeebpms.org/manual/latest/reference/bpmn20/events/message-events/)). Ta sama nazwa trafi później do skryptu konsumenta.

W przykładach na tej stronie nazwa wiadomości to `lowcodeDemoMessage`.

![Ilustracja 1. Przykładowy proces z krokiem typu "Message Intermediate Catch Event"](https://1082717226-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F2CssJT0zIo4SJQLbSZ6l%2Fuploads%2Fgit-blob-74ec36fdac49329c020b3a5f516809e7a7124e17%2Fi1.png?alt=media)

![Ilustracja 2. Przykładowa konfiguracja kroku typu "Message Intermediate Catch Event"](https://1082717226-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F2CssJT0zIo4SJQLbSZ6l%2Fuploads%2Fgit-blob-166b74f6b97fb0a70f393eee8e1f0025ff8763e7%2Fi2.png?alt=media)

### Wyślij identyfikator instancji procesu do systemu zewnętrznego

Konsument wznawia proces wyłącznie na podstawie identyfikatora instancji procesu (`processInstanceId`). Wznowienie po kluczu biznesowym nie jest dostępne. System zewnętrzny musi więc dostać ten identyfikator w żądaniu i odesłać go w odpowiedzi.

W przykładach na tej stronie wiadomość z identyfikatorem instancji procesu trafia na kolejkę `eximee_demo_integration`. Taką wiadomość można wysłać ze skryptu z pomocą Eximee, jest to opisane na stronie [Lowcode do RabbitMQ](https://docs.eximee.com/eksploatacja-aplikacji/obsluga-zdarzen/lowcode-do-rabbitmq.md#przykladowy-skrypt-uslugowy). Taką wiadomość może również wysłać system zewnętrzny.

{% hint style="warning" %}
Proces musi czekać na kroku "Message Intermediate Catch Event", zanim nadejdzie odpowiedź. Jeżeli odpowiedź przyjdzie wcześniej, na przykład gdy system zewnętrzny odpowie natychmiast, a proces nie zdążył jeszcze dojść do kroku oczekiwania, Eximee BPMS odrzuci wiadomość. Platforma nie ponawia wtedy próby: wiadomość trafia do DLQ albo, jeżeli DLQ nie skonfigurowano, przepada. Projektuj proces tak, aby po wysłaniu żądania krok oczekiwania był osiągany bez zbędnych kroków pośrednich.
{% endhint %}

## Krok 3. Uzgodnij format wiadomości

Platforma nie narzuca formatu wiadomości. Uzgodnij go z zespołem systemu zewnętrznego przed napisaniem konsumenta. Wiadomość musi zawierać identyfikator instancji procesu.

Przykład formatu używanego dalej na tej stronie:

```json
{
  "processInstanceId": "8f0b7a52-0c43-11ef-9a1c-0242ac120002",
  "data": "przykładowa wartość"
}
```

Treść wiadomości jest odczytywana jako tekst w kodowaniu UTF-8. Jeżeli wiadomość to JSON, skrypt sam zamienia ją na obiekt funkcją `JSON.parse`.

## Krok 4. Utwórz konsumenta w Eximee Designer

1. W Eximee Designer otwórz **Biblioteka** → **Konsumenci**.
2. Kliknij **Dodaj Konsumenta**.
3. Wprowadź nazwę konsumenta ustaloną z administratorami w kroku 1, na przykład `message_consumer_demo`.
4. Napisz skrypt konsumenta i zapisz go.

{% hint style="warning" %}
Aktualnie konsument nie jest częścią aplikacji. Przy przenoszeniu aplikacji na inne środowisko konsument nie zostanie przeniesiony razem z nią. Przenieś go osobno, oprócz aplikacji.
{% endhint %}

Ten sam konsument może obsługiwać wiadomości z RabbitMQ i z Kafki. O tym, skąd przychodzą wiadomości, decyduje wyłącznie konfiguracja administratora.

### Przykładowy skrypt konsumenta

Skrypt konsumenta `message_consumer_demo` odbiera wiadomość w formacie z kroku 3, sprawdza ją i wznawia proces:

```javascript
function consumeMessage(context) {
    const MESSAGE_NAME = 'lowcodeDemoMessage';
    const message = context.getMessage();

    let payload;
    try {
        payload = JSON.parse(message.value);
    } catch (e) {
        // wyjątek: wiadomość trafi do DLQ
        throw new Error('Treść wiadomości nie jest poprawnym JSON-em');
    }

    if (!payload.processInstanceId) {
        // wyjątek: wiadomość trafi do DLQ
        throw new Error('Brak processInstanceId w treści wiadomości');
    }
    const processInstanceId = String(payload.processInstanceId);

    // zmienne procesu ustawiane razem z wiadomością; wartości muszą być tekstem
    const variables = {
        rabbitData: (payload.data === undefined || payload.data === null) ? '' : String(payload.data)
    };

    // jeżeli proces nie czeka na tę wiadomość, funkcja zgłosi błąd i wiadomość trafi do DLQ
    api.process.v1.byInstanceId(processInstanceId).correlateMessage(MESSAGE_NAME, variables);
    Logger.info('Proces wznowiony [processInstanceId={}]', nonsensitive(processInstanceId));
}
```

Po odebraniu przykładowej wiadomości z kroku 3 proces o identyfikatorze `8f0b7a52-0c43-11ef-9a1c-0242ac120002` przechodzi dalej i otrzymuje zmienną `rabbitData` = `przykładowa wartość`.

### Zasady pisania konsumenta

* Wznów proces wywołaniem `api.process.v1.byInstanceId(processInstanceId).correlateMessage(nazwaWiadomosci, zmienne)`. Konsument nie działa w kontekście żadnego procesu, więc identyfikator instancji wskazuj zawsze jawnie, przez `byInstanceId`.
* Zmienne przekazywane do `correlateMessage` muszą mieć wartości tekstowe. Liczby i wartości logiczne zamieniaj na tekst funkcją `String()`. Drugi parametr można pominąć, jeżeli proces nie potrzebuje żadnych zmiennych.

{% hint style="info" %}
Konsumenci mają ograniczony dostęp do API. Mogą korzystać tylko z obiektu `Logger` i z funkcji `api.process.v1.byInstanceId(processInstanceId)`: `correlateMessage`, `getProcessInfo` i `getUserTaskInfo`. Pozostałe funkcje `api.process`, na przykład `startProcess` i `setAccessGroups`, są w konsumencie niedostępne, tak samo jak wywołania REST i wysyłka wiadomości. Więcej o API procesu: [Operacje i dostęp do danych procesu](https://github.com/Consdata/eximee-docs/tree/main/budowanie-aplikacji/logika-biznesowa/scriptcode/skrypty-scriptservice/api-skryptow/operacje-i-dostep-do-danych-procesu.md)
{% endhint %}

### Zakończenie skryptu a los wiadomości

To, co stanie się z wiadomością, zależy wyłącznie od tego, jak zakończy się skrypt:

| Zakończenie skryptu                                                  | Co dzieje się z wiadomością                                                                     |
| -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| Skrypt kończy się normalnie albo przez `return`                      | Wiadomość zostaje uznana za obsłużoną i usunięta z kolejki.                                     |
| Skrypt zgłasza wyjątek (`throw`), także wyjątek z `correlateMessage` | Wiadomość zostaje odrzucona i trafia do DLQ. Jeżeli DLQ nie skonfigurowano, wiadomość przepada. |

{% hint style="danger" %}
Nie przechwytuj błędów w skrypcie po to, żeby je tylko zalogować. Jeżeli skrypt przechwyci błąd i zakończy się normalnie, wiadomość zostanie usunięta z kolejki i nie trafi do DLQ, więc nie będzie można jej przeanalizować ani przetworzyć ponownie. Używaj `return` tylko dla wiadomości, które świadomie chcesz pominąć.
{% endhint %}

Platforma nie ponawia przetwarzania wiadomości, której skrypt nie przetworzył. Taka wiadomość od razu trafia do DLQ.

## Dane wiadomości dostępne w skrypcie

Funkcja `context.getMessage()` zwraca wiadomość wraz z metadanymi:

| Pole               | Typ      | Opis                                                                                                                   |
| ------------------ | -------- | ---------------------------------------------------------------------------------------------------------------------- |
| `value`            | `string` | Treść wiadomości.                                                                                                      |
| `headers`          | obiekt   | Nagłówki wiadomości. Wartość nagłówka odczytasz funkcją `headers.get('nazwa')`.                                        |
| `key`              | `string` | Identyfikator wiadomości (właściwość `message_id`). `null`, jeżeli nadawca go nie ustawił.                             |
| `topic`            | `string` | Nazwa kolejki, z której pochodzi wiadomość.                                                                            |
| `timestamp`        | `number` | Czas utworzenia wiadomości w milisekundach od 1970-01-01 (właściwość `timestamp`). `0`, jeżeli nadawca go nie ustawił. |
| `queue.queue`      | `string` | Nazwa kolejki, z której pochodzi wiadomość.                                                                            |
| `queue.exchange`   | `string` | Exchange, z którego wiadomość trafiła na kolejkę. Pusty przy exchange domyślnym.                                       |
| `queue.routingKey` | `string` | Routing key, z którym wiadomość trafiła na kolejkę.                                                                    |

Pole `event` jest wypełniane tylko w wiadomościach z Kafki. W wiadomości z RabbitMQ ma wartość `null`, więc skrypt obsługujący oba źródła rozpozna po nim, skąd przyszła wiadomość.

{% hint style="warning" %}
Nagłówki odczytuj funkcją `get`: `message.headers.get('x-correlation-id')`. Zapis `message.headers['x-correlation-id']` zwraca `undefined`.
{% endhint %}

Przykład odczytu metadanych:

```javascript
function consumeMessage(context) {
    const message = context.getMessage();

    const correlationId = message.headers.get('x-correlation-id');
    Logger.info('Odebrano wiadomość [kolejka={}, exchange={}, routingKey={}, correlationId={}]',
        nonsensitive(message.queue.queue),
        nonsensitive(message.queue.exchange),
        nonsensitive(message.queue.routingKey),
        nonsensitive(correlationId));
}
```

## Rozwiązywanie problemów

| Objaw                                                                                                   | Możliwa przyczyna                                                                                                                                             | Rozwiązanie                                                                                                                                  |
| ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| Wiadomość trafia do DLQ, a proces nie przechodzi dalej                                                  | Proces nie czekał na kroku oczekiwania, nazwa wiadomości w `correlateMessage` różni się od nazwy w procesie albo identyfikator instancji procesu jest błędny. | Sprawdź log aplikacji `lowcode-queue-consumer` dla tej wiadomości. Upewnij się, że nazwa wiadomości jest identyczna w procesie i w skrypcie. |
| Wiadomość znika i nie ma jej w żadnej kolejce                                                           | Skrypt zakończył się przez `return` albo przechwycił błąd, albo dla kolejki nie skonfigurowano DLQ.                                                           | Zgłaszaj wyjątek dla wiadomości, których nie da się przetworzyć, i poproś administratorów o skonfigurowanie DLQ.                             |
| Po przeniesieniu aplikacji na inne środowisko wiadomości trafiają do DLQ, a proces nie przechodzi dalej | Konsumenta nie przeniesiono na to środowisko. Konsument nie jest częścią aplikacji i nie przenosi się razem z nią.                                            | Przenieś konsumenta na to środowisko osobno, oprócz aplikacji.                                                                               |
| Zmiana w skrypcie konsumenta nie działa                                                                 | Konsument nie został zapisany albo cache ma długi TTL.                                                                                                        | Zapisz konsumenta i poproś administratorów o wyczyszczenie cache.                                                                            |

Problemy z uruchomieniem aplikacji, połączeniem z brokerem i mapowaniem kolejek opisuje strona [Konfiguracja konsumentów RabbitMQ](https://docs.eximee.com/eksploatacja-aplikacji/obsluga-zdarzen/konsumenci-rabbitmq/konfiguracja.md#rozwiazywanie-problemow). Tam też znajdziesz sposób sprawdzenia działania konsumenta wiadomością testową.

## Powiązane strony

* [Konfiguracja konsumentów RabbitMQ](https://docs.eximee.com/eksploatacja-aplikacji/obsluga-zdarzen/konsumenci-rabbitmq/konfiguracja.md) — konfiguracja aplikacji `lowcode-queue-consumer`, kolejek i DLQ.
* [Lowcode do RabbitMQ](https://docs.eximee.com/eksploatacja-aplikacji/obsluga-zdarzen/lowcode-do-rabbitmq.md) — wysyłka wiadomości na kolejkę ze skryptów i zadań skryptowych.
* [Konsumenci Kafka](https://docs.eximee.com/eksploatacja-aplikacji/obsluga-zdarzen/konsumenci-kafka.md) — ten sam mechanizm dla wiadomości z Kafki.
* [Operacje i dostęp do danych procesu](https://github.com/Consdata/eximee-docs/tree/main/budowanie-aplikacji/logika-biznesowa/scriptcode/skrypty-scriptservice/api-skryptow/operacje-i-dostep-do-danych-procesu.md) — API `api.process`.
* [API Zadań skryptowych](https://docs.eximee.com/budowanie-aplikacji/logika-biznesowa/scriptcode/zadanie-skryptowe-scripttask/api-zadan-skryptowych.md) — pisanie zadań skryptowych w procesie.


---

# 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/eksploatacja-aplikacji/obsluga-zdarzen/konsumenci-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.
