Konsumenci Kafka

Dostępność funkcjonalności zależy od licencji i może nie być dostępna we wszystkich wdrożeniach.

Cel

Procesy w Eximee mogą składać się z kroków, które wymagają asynchronicznej komunikacji z systemami zewnętrznymi. Przykładowo: 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 Kafki. Konsumenci Kafka służą właśnie do obsługi takich odpowiedzi. Używamy ich do odebrania wiadomości, wstępnego przetworzenia zawartych w nich danych oraz powiadamiania Eximee BPMS, by kontynuować wykonywanie procesu.

Powiązanie topika Kafki z Konsumentem Kafki

Każdy konsument Kafki musi być powiązany z topikiem, na który będzie nasłuchiwał. Do ustalenia takiego mapowania potrzebujemy:

• nazwy topicu - powinniśmy ją dostać odgórnie,

• nazwy konsumenta Kafki - ustalamy ją sami, analogicznie do nazwy innych artefaktów,

• mając obie nazwy, możemy zgłosić administratorom prośbę o dodanie do konfiguracji mapowania topicu na konsumenta Kafki (podając obie nazwy). Bez mapowania, będziemy w stanie napisać konsumenta Kafki, jednak nie będzie on odbierał wiadomości.

Konsumenci Kafka w Procesie

Konsumenci Kafka mogą działać niezależnie, jednak zazwyczaj będą powiązani z procesem w Eximee BPMS. Konsumenci Kafka w procesie biorą udział w zdarzeniach typu "Message". Na kroku tego typu Eximee BPMS oczekuje na wiadomość, by móc kontynuować wykonywanie procesu. Wiadomość może zostać wysłana z konsumenta Kafki.

Ilustracja 1. Przykładowy proces z krokiem typu "Message Intermediate Catch Event" (zdarzenie "Oczekuj na powiadomienie z banku")

Na etapie projektowania procesu musimy pamiętać o uzupełnieniu nazwy wiadomości w konfiguracji. Musi spełniać ograniczenia Eximee BPMS (Message Events) i będzie nam potrzebna później, przy powiązaniu kroku procesu z konsumentem Kafki.

Ilustracja 2. Przykładowa konfiguracja kroku typu "Message Intermediate Catch Event"

Tworzenie Konsumenta Kafka

W Eximee Designer wybieramy odpowiednio Biblioteka → Konsumenci Kafka. Tutaj, podobnie do pozostałych artefaktów, znajduje się przycisk Dodaj Konsumenta Kafka:

Ilustracja 3. Zakładka z typem artefaktów: Konsumenci Kafka

Konsumenci Kafka mają ograniczony dostęp do API i mogą korzystać tylko z funkcji dostępnych w api.process.*. Więcej informacji o API: Operacje i dostęp do danych procesu

Przykład użycia konsumenta Kafka:

function callService(context) {
    // pobranie treści wiadomości z kontekstu
    var message = context.getMessage().value;
    // przetwarzanie wiadomości
    var jsonValue = JSON.parse(stringValue);
    var processInstanceId = jsonValue.processInstanceId;
    // wysyłka wiadomości do Eximee BPMS z informacją, by kontynuować proces
    api.process.v1.byInstanceId(messageValue.processInstanceId).correlateMessage('get-notification', null);
    return;
}

Format wiadomości nie jest narzucany, więc struktura i typ zawartych w niej danych powinny być ustalone odgórnie, by być w stanie je poprawnie przetworzyć.

Pisząc konsumenta Kafki, niemal zawsze będziemy zaczynać od pobrania treści wiadomości, używając context.getMessage().value;. To jak później możemy przetworzyć wiadomość, zależy od ustalonego formatu wiadomości, więc zestaw i typ pól w każdym przypadku mogą być inne. Ważne jest, aby na etapie ustaleń pamiętać o identyfikatorze instancji procesu. W przykładzie jest to pole processInstanceId. Dzięki tej wartości wiemy, której instancji procesu dotyczy dany komunikat.

Pobranie danych z wiadomości

Używając context.getMessage() pobieramy wiadomość i jej metadane. Obiekt, który jest zwracany przez tę funkcję, ma następujące pola:

Nazwa	Typ	Opis
value	string	Treść (payload) wiadomości.
headers	object	Nagłówki wiadomości Kafka jako mapa klucz–wartość
key	string	Klucz wiadomości Kafka. Może być null, jeśli nie został uzupełniony.
topic	string	Nazwa topiku Kafka, z którego pochodzi wiadomość
partition	number	Numer partycji topiku, z której pochodzi wiadomość
offset	number	Znacznik czasu (epoch ms) utworzenia wiadomości
timestamp	number	Czas utworzenia wiadomości

Należy mieć na uwadze, że:

• context.getMessage() - pobiera cały obiekt wiadomości wraz z metadanymi,

• context.getMessage().value - pobiera samą treść wiadomości. Najczęściej będziemy korzystać właśnie z tej formy.