# Lowcode do kafki

{% 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ą kafkę i wskazany topic bezpośrednio z poziomu wniosków (skrypty) i procesów bpmn (zadania skryptowe).

## Przykłady użycia

* Aktualizacja danych w hurtowni danych
* Powiadamianie CRM o zmianach statusu procesu
* Komunikacja z systemami zewnętrznymi (np. systemami banku)

## Użycie w skrypcie/zadaniu skryptowym

> Zwróć uwagę, że nazwa instancji Kafka ("kafkaid" w przykładzie) musi być pisana małymi literami i bez znaków specjalnych.

```js
try {
    api.events.v1.publishAsync(
        "kafkaid",                  // nazwa instancji Kafka (skonfigurowanej przez administratora, pisana tylko małymi literami, bez znaków specjalnych)
        "topicName",                // nazwa topica (skonfigurowanego przez administratora)    
        {                           // treść wiadomości – musi być poprawnym JSON-em
            "id": "123",
            "status": {
                "code": "OK",
                "message": "Everything is fine!"
            },
            "list": [1, 2, 3],
            "boolean": true,
            "date": new Date()
        },
        "key",                      // klucz wiadomości (opcjonalny – trzeba go nadawać, jeżeli potrzebujemy zachować kolejność zdarzeń)
        {                           // nagłówki (opcjonalne)
            "header1": "header1-value",
            "header2": "header2-value"
        }
    );
} catch (e) {
    // obsługa błędu
}
```

## Ważne informacje

* Wysyłka jest asynchroniczna – skrypt nie czeka na potwierdzenie dostarczenia wiadomości
* Należy pamiętać o obsłudze wyjątków. Funkcja może rzucić błąd w przypadku braku połączenia do Kafki lub przepełnienia bufora wiadomości do wysłania w aplikacji
* Wykonanie funkcji bez błędu potwierdza dodanie wiadomości do bufora, nie gwarantuje bezbłędnego wysłania wiadomości. Nie jesteśmy w stanie przechwycić błędów samej wysyłki
* Treść wiadomości musi być poprawnym JSON-em – przekazywany obiekt jest automatycznie serializowany
* Klucz jest opcjonalny, ale zalecany gdy zależy Ci na kolejności wiadomości w ramach jednej partycji
* Timeout wysyłki jest konfigurowany przez administratora – nie można go zmieniać z poziomu skryptu
* Topic'i są tworzone i zarządzane przez administratorów
* `kafkaId` musi odpowiadać nazwie instancji Kafka skonfigurowanej w aplikacji