> 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/lowcode-do-rabbitmq.md).

# Lowcode do 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

Umożliwienie wysyłania wiadomości na wskazaną kolejkę RabbitMQ bezpośrednio z poziomu wniosków (skrypty) i procesów bpmn (zadania skryptowe).

## Przykłady użycia

* Przekazanie do systemu zewnętrznego żądania, na które odpowiedź wróci asynchronicznie (patrz [Konsumenci RabbitMQ](https://docs.eximee.com/eksploatacja-aplikacji/obsluga-zdarzen/konsumenci-rabbitmq.md))
* Powiadamianie systemów zewnętrznych o zmianach statusu procesu
* Komunikacja z systemami zewnętrznymi (np. systemami banku)

## Jak to działa

```
1. Skrypt                  wywołuje api.queue.v1.publishAsync z nazwą połączenia, routing key,
                           treścią i nagłówkami wiadomości
2. Aplikacja Eximee        zamienia treść na JSON i publikuje wiadomość na exchange
                           skonfigurowany dla tego połączenia, z podanym routing key
3. Broker RabbitMQ         kieruje wiadomość do kolejek, które mają z exchange binding z tym routing key
```

Połączenie z brokerem i exchange ustawia administrator w konfiguracji aplikacji. Skrypt wskazuje tylko nazwę połączenia i routing key.

## Krok 1. Ustal dane z administratorami

Przed napisaniem skryptu ustal z administratorami:

* **nazwę połączenia**, przez które skrypt wysyła wiadomości, na przykład `integration`. Projektant procesu może zaproponować nazwę, a administratorzy ją potwierdzają albo wskazują istniejące połączenie. Nazwa to jedno słowo, bez znaku `_`,
* **dokąd ma trafić wiadomość**, czyli exchange i routing key. Te dwie wartości ustalasz razem, bo od exchange zależy, czym jest routing key:
  * przy exchange domyślnym (pusta nazwa exchange w konfiguracji) routing key to nazwa kolejki docelowej, więc wystarczy ustalić kolejkę,
  * przy własnym exchange ustal jego nazwę i routing key. Na którą kolejkę trafi wiadomość, decydują bindingi zdefiniowane na brokerze,
* **skąd wysyłasz wiadomości**: ze skryptu usługowego w formularzu, z zadania skryptowego w procesie albo z obu. Od tego zależy, w których aplikacjach administratorzy skonfigurują połączenie.

W przykładach na tej stronie wiadomości są wysyłane przez połączenie `integration` z exchange domyślnym na kolejkę `eximee_demo_integration`. Z tej kolejki wiadomości odbiera konsument opisany na stronie [Konsumenci RabbitMQ](https://docs.eximee.com/eksploatacja-aplikacji/obsluga-zdarzen/konsumenci-rabbitmq.md).

### Przykład zgłoszenia

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

```
Prośba o konfigurację wysyłki do RabbitMQ:
- nazwa połączenia: integration
- exchange: domyślny
- kolejka docelowa (routing key): eximee_demo_integration
- wysyłka z: skryptu usługowego w formularzu, zadania skryptowego w procesie
```

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

## Krok 2. Wyślij wiadomość ze skryptu

```js
api.queue.v1.publishAsync(
    'integration',                    // nazwa połączenia z kroku 1, małymi literami
    'eximee_demo_integration',        // routing key z kroku 1: przy exchange domyślnym nazwa kolejki
    {                                 // treść wiadomości: obiekt zamieniany na JSON
        processInstanceId: '123',
        data: 'przykładowa wartość'
    },
    {                                 // nagłówki: wartości tekstowe; gdy ich nie ma, podaj {}
        header1: 'header1-value'
    }
);
```

| Parametr         | Opis                                                                                                                                                         | Skąd wziąć wartość                                 |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------- |
| nazwa połączenia | Nazwa połączenia z konfiguracji aplikacji, zapisana małymi literami. Wielkość liter ma znaczenie: `'INTEGRATION'` zamiast `'integration'` kończy się błędem. | Nazwa ustalona z administratorami w kroku 1.       |
| routing key      | Routing key wiadomości. Przy exchange domyślnym to nazwa kolejki docelowej.                                                                                  | Routing key ustalony z administratorami w kroku 1. |
| treść            | Wartość, którą funkcja zamienia na JSON (`JSON.stringify`). Opis w sekcji [Treść i nagłówki wiadomości](#tresc-i-naglowki-wiadomosci).                       | Ustalasz z odbiorcą wiadomości.                    |
| nagłówki         | Obiekt z nagłówkami wiadomości. Parametr jest wymagany: jeżeli nie wysyłasz nagłówków, podaj `{}`.                                                           | Ustalasz z odbiorcą wiadomości.                    |

Funkcja wraca po przekazaniu wiadomości do brokera. Nie czeka na potwierdzenie, że broker przyjął wiadomość ani że odbiorca ją przetworzył.

### Przykładowy skrypt usługowy

Skrypt usługowy pobiera parametry `processInstanceId` i `data`, buduje wiadomość i wysyła ją na kolejkę `eximee_demo_integration`:

```js
function callService(context) {
    const CONNECTION_ID = 'integration';
    const ROUTING_KEY = 'eximee_demo_integration';

    const processInstanceId = context.getFirstParameter('processInstanceId');
    const data = context.getFirstParameter('data');

    if (!processInstanceId) {
        Logger.error('Rabbit demo message not published, processInstanceId is empty');
        return [{'published': 'false'}];
    }

    const payload = {
        processInstanceId: String(processInstanceId),
        data: (data === undefined || data === null) ? '' : String(data)
    };

    api.queue.v1.publishAsync(CONNECTION_ID, ROUTING_KEY, payload, {});
    Logger.info('Rabbit demo message published [routingKey={}, processInstanceId={}]',
        nonsensitive(ROUTING_KEY), nonsensitive(processInstanceId));

    return [{'published': 'true'}];
}
```

Dla parametrów `processInstanceId` = `8f0b7a52-0c43-11ef-9a1c-0242ac120002` i `data` = `przykładowa wartość` na kolejkę `eximee_demo_integration` trafia wiadomość:

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

### Przykładowe zadanie skryptowe

Zadanie skryptowe wysyła wiadomość z identyfikatorem instancji procesu. Jeżeli wysyłka się nie uda, zgłasza na zadaniu incydent, więc proces zatrzymuje się do czasu interwencji:

```js
function handle(task, context) {
    try {
        api.queue.v1.publishAsync('integration', 'eximee_demo_integration', {
            processInstanceId: task.getProcessInstanceId(),
            data: task.getVariable('data')
        }, {});
    } catch (e) {
        context.handleFailure('Nie udało się wysłać wiadomości do RabbitMQ: ' + e.message);
        return;
    }
    context.complete({});
}
```

Więcej o zadaniach skryptowych: [API Zadań skryptowych](https://docs.eximee.com/budowanie-aplikacji/logika-biznesowa/scriptcode/zadanie-skryptowe-scripttask/api-zadan-skryptowych.md).

## Treść i nagłówki wiadomości

Funkcja zawsze zamienia treść na JSON funkcją `JSON.stringify`. Wiadomość jest wysyłana z content type `application/json`, kodowaniem `UTF-8` i jako trwała (persistent).

| Przekazana treść                        | Treść wiadomości na kolejce                                       |
| --------------------------------------- | ----------------------------------------------------------------- |
| `{processInstanceId: '123', data: 'x'}` | `{"processInstanceId":"123","data":"x"}`                          |
| `{d: new Date(0)}`                      | `{"d":"1970-01-01T00:00:00.000Z"}`: data jako tekst w strefie UTC |
| `'abc'`                                 | `"abc"`: tekst w cudzysłowie                                      |
| `JSON.stringify({a: 1})`                | `"{\"a\":1}"`: JSON zakodowany drugi raz                          |
| `null`                                  | `null`                                                            |
| `undefined`                             | `undefined`: treść, która nie jest poprawnym JSON-em              |

{% hint style="warning" %}
Przekazuj treść jako obiekt. Nie zamieniaj jej samodzielnie na tekst funkcją `JSON.stringify`: odbiorca dostanie wtedy tekst w cudzysłowie zamiast obiektu JSON.
{% endhint %}

Nagłówki:

* Wartości nagłówków muszą być tekstem. Liczba albo wartość logiczna kończy się błędem; zamień ją funkcją `String()`.
* Nagłówek z wartością `null` jest pomijany.
* Wiadomość nie ma ustawionego identyfikatora (`message_id`) ani znacznika czasu (`timestamp`). Jeżeli odbiorca ich potrzebuje, przekaż je w treści albo w nagłówkach.

## Obsługa błędów

Funkcja zgłasza błąd, który możesz przechwycić w bloku `try/catch`, gdy:

| Sytuacja                                                                                     | Komunikat błędu                                      |
| -------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| W aplikacji nie skonfigurowano połączenia o podanej nazwie albo nazwa ma inną wielkość liter | `No queue client found. [connectionId=<nazwa>]`      |
| Broker jest niedostępny                                                                      | `org.springframework.amqp.AmqpConnectException: ...` |
| Wartość nagłówka nie jest tekstem                                                            | `ClassCastException`                                 |
| Brakuje parametru nagłówków                                                                  | `Can't find method ... publishAsync(...)`            |

{% hint style="danger" %}
Funkcja nie zgłasza błędu, gdy broker nie może dostarczyć wiadomości: przy routing key, dla którego nie ma żadnej kolejki, i przy exchange, którego nie ma na brokerze. Wiadomość przepada bez śladu. Przed uruchomieniem sprawdź z administratorami nazwę połączenia, routing key i bindingi na brokerze, a po pierwszej wysyłce sprawdź, czy wiadomość trafiła na kolejkę.
{% endhint %}

## Rozwiązywanie problemów

| Objaw                                                       | Możliwa przyczyna                                                                                                                                                  | Rozwiązanie                                                                                                                                                                                                                    |
| ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Błąd `No queue client found. [connectionId=...]`            | Nazwa połączenia w skrypcie różni się od konfiguracji, jest zapisana wielkimi literami albo połączenie nie jest skonfigurowane w aplikacji, która wykonuje skrypt. | Użyj nazwy małymi literami. Poproś administratorów o sprawdzenie konfiguracji (strona [Konfiguracja wysyłki do RabbitMQ](https://docs.eximee.com/eksploatacja-aplikacji/obsluga-zdarzen/lowcode-do-rabbitmq/konfiguracja.md)). |
| Skrypt kończy się bez błędu, a wiadomości nie ma na kolejce | Błędny routing key, brak bindingu z kolejką albo exchange, którego nie ma na brokerze.                                                                             | Sprawdź z administratorami routing key i bindingi na brokerze.                                                                                                                                                                 |
| Odbiorca dostaje tekst w cudzysłowie zamiast obiektu JSON   | Treść została zamieniona na tekst przed wywołaniem funkcji.                                                                                                        | Przekaż treść jako obiekt.                                                                                                                                                                                                     |
| Błąd `ClassCastException`                                   | Wartość nagłówka nie jest tekstem.                                                                                                                                 | Zamień wartość funkcją `String()`.                                                                                                                                                                                             |

## Powiązane strony

* [Konfiguracja wysyłki do RabbitMQ](https://docs.eximee.com/eksploatacja-aplikacji/obsluga-zdarzen/lowcode-do-rabbitmq/konfiguracja.md) — konfiguracja połączeń w aplikacjach wykonujących skrypty.
* [Konsumenci RabbitMQ](https://docs.eximee.com/eksploatacja-aplikacji/obsluga-zdarzen/konsumenci-rabbitmq.md) — odbiór wiadomości z kolejki i wznawianie procesu.
* [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/lowcode-do-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.
