Rejestracja zdarzeń procesu

Rejestracja zdarzeń

Jest to dziennik zdarzeń, w którym chronologicznie rejestrowane są zdarzenia zaistniałe w sprawie. W celu włączenia rejestracji zdarzeń należy ustawić parametr w konfiguracji platformy: CASE_HISTORY_ENABLED="true"

Rejestrujemy dwa typy zdarzeń:

Systemowe - wykonywane przez użytkowników (Klienta i Pracownika):

• utworzenie sprawy,
• podjęcie kroku manualnego przez użytkownika (claim),
• zapisanie kroku manualnego przez użytkownika (zapisanie zadania - przerwanie realizacji - tu nie ma unClaim),
• odłożenie kroku manualnego przez użytkownika (unClaim),
• finalizacja kroku manualnego przez użytkownika,
• zakończenie sprawy (koniec procesu),
• zmiana priorytetu sprawy.

Biznesowe - zdarzenia rejestrowane w Historii przez proces, w momentach zdefiniowanych w procesie (np. w kroku automatycznym lub z poziomu formularza).

Zdarzenie biznesowe posiada atrybuty wspólne:

• typ zdarzenia: biznesowe,
• rodzaj zdarzenia,
• osoba przypisana,
• opis zdarzenia,
• struktura z atrybutami zdarzenia,
• datę zdarzenia.

Zdarzenia Systemowe

Konfiguracja

W celu wykorzystania pluginu służącego do dodawania poszczególnych zdarzeń systemowych na topic, należy ustawić w konfiguracji namiary na router-api poprzez config ROUTER_ENGINE_CASE_HISTORY_ROUTER_API_URL, np:

ROUTER_ENGINE_CASE_HISTORY_ROUTER_API_URL=http://eximee-router-api:8080/

Automatyczna publikacja zdarzeń dla typów

• PROCESS_START - Start procesu
• PROCESS_END - Zakończenie procesu
• CLAIM_TASK - Przypisanie użytkownika
• UNCLAIM_TASK - Odpisanie użytkownika
• ASSIGNEE_TASK - Przypisanie użytkownika przez innego użytkownika
• SEND_USER_TASK - Wysłanie zadanie użytkownika
• SAVE_TASK - Zapis zadania
• PROCESS_PRIORITY_CHANGE - Zmiana priorytetu zadania

Zdarzenia Biznesowe

Konfiguracja

W celu rejestracji zdarzeń biznesowych, należy w aplikacji biznesowej dodać zależność:

events-connector

<dependency>
   <groupId>com.consdata.eximee</groupId>
   <artifactId>events-connector</artifactId>
   <version>${eximee-platform.version}</version>
</dependency>

Następnie należy dodać konfigurację:

events.connector.rest.events.url=${ROUTER_API_URL}

gdzie ROUTER_API_URL to adres aplikacji router-api.

Następnie w kodzie aplikacji np. w Handlerze zadania camundowego, należy wstrzyknąć bean'a CaseHistoryBusinessMessageConnector i wywołać na nim metodę publish przekazując obiekt BusinessMessage.

caseHistoryBusinessMessageConnector.publish(BusinessMessage.builder()
        .businessKey(externalTask.getBusinessKey())               // Biznesowy klucz procesu - wymagany
        .eventCode("Wysyłanie powiadomienia")                     // Kod zdarzenia, który będzie wyświetlany na liście historii sprawy - wymagany
        .processInstanceId(externalTask.getProcessInstanceId())   // Identyfikator procesu - wymagany
        .processKey(externalTask.getProcessDefinitionKey())       // Klucz procesu - wymagany
        .processName("NazwaProcesu")                              // Nazwa procesu w Camunda - wymagany
        .eventDescription("Opis zadania")                         // Opis zdarzenia, który będzie wyświetlany na liście historii sprawy - opcjonalny
        .userId("123456")                                         // Identyfikator użytkownika, który wykonał daną czynność - wymagany
        .params(Map.of(                                           // Parametry biznesowe, które będą wyświetlane w zakładce Historii sprawy, w szczegółach zdarzenia - opcjonalne                                                          
               "Numer telefonu", externalTask.getVariable("authorizationPhoneNumber"),
               "Priorytet", StringUtils.defaultString(externalTask.getVariable("priority"), "BRAK"))
        )
        .build());

W polu userId przekaż identyfikator użytkownika, a nie jego nazwę. Na liście historii sprawy wyświetlana jest nazwa ustalona na podstawie tego identyfikatora, a gdy nie da się jej ustalić — sam identyfikator.

Pobieranie informacji do zdarzeń systemowych i zdarzeń biznesowych

W przypadku zdarzenia "odłożenie kroku manualnego przez użytkownika" (unclaim), przy wywołaniu innym niż w ramach Router 2 (tzn. bezpośrednio poprzez API Camundy), należy dodać obsługę zdarzenia biznesowego, które przechwyci wywołanie unclaim.

W celu właściwego rejestrowania kanału zdarzenia, należy dodać na każdym wniosku zmienną router_channel:

Ilustracja 5. Zmienna sesyjna "router_channel"

Ilustracja 6. Parametr wejściowy "router_channel"

Kafka

Konfiguracja Kafki dla rejestracji zdarzeń procesu:

spring.kafka.bootstrap-servers=${KAFKA_BOOTSTRAP_SERVERS:}
event.topic.all.name=${EVENT_TOPIC_ALL_NAME:all}
event.topic.all.groupId=${EVENT_TOPIC_ALL_GROUP_ID:case-history}

Topic

Na środowisku kafka powstał topic 'all'. Do nowego topic'u przychodzą wszystkie zdarzenia, w tym te z rejestracją zdarzeń procesu. Aplikacja router-api pobiera z topic'a all dane dla zakładki historii sprawy w Eximee Dashboard.

Przykładowy obiekt zdarzenia, który trafia na kolejkę:

{
  "origin": "BUSINESS/SYSTEM",
  "type": "START_PROCESS",
  "timestamp: "1673525273",
  "payload" : {
        "processInstanceId": "123e4567-e89b-12d3-a456-426614174000",
        "uuid": "789a4567-e89b-12d3-a456-426614174222",     
        "processName": "nazwaProcesu",
        "businessKey": "businessKey001",
        "processKey": "processName",
        "assignee" : "user001",
        "eventDescription": "Description0001",
        "params": {
            "Etykieta 1": "Wartość 1",
            "Etykiata 2": "Wartość 2"
        }
   }
}

Obsługa błędów

W przypadku błędu podczas pobierania zdarzenia, informacje o błędzie trafiają do logu eximee-events-errors.log.

Przykładowy wpis o błędzie:

[router2-api-docker] 2023-03-03 15:14:34.074 [key=c1411d4a-3d9e-47fc-9970-711138451a06][offset=43][value=EventData(origin=SYSTEM, type=PROCESS_PRIORITY_CHANGE, timestamp=1673541340, payload={processInstanceId=f442acfd-877f-11ed-9beb-0242ac120003, eventDescription=Ustawienie wysokiego priorytetu sprawy, channel=EXIMEE_DASHBOARD, processKey=kredytHipoteczny, username=user0001, params={}}))][topic=all] [org.springframework.kafka.KafkaListenerEndpointContainer#0-0-C-1] ERROR java.lang.ClassCastException: Cannot cast java.lang.String to java.lang.Boolean

gdzie:

• [router2-api-docker] - identyfikator kontenera, który zgłosił błąd,
• key - klucz eventu,
• offset - indeks wiadomości w kafce,
• value - przetwarzany obiekt,
• topic - topic kafkowy, z którego nastąpiła konsumpcja eventu.

Endpoint diagnostyczny dla błędów podczas pobierania zdarzeń z historii sprawy

Powstał endpoint sprawdzający czy jest wpis w aktualnym pliku z błędami dla zdarzeń:

GET TRAEFIK_HOST:TRAEFIK_PORT/router-api/case-history/event/errors

Response: false - plik jest pusty true - w pliku są jakieś błędy

Ponawianie błędów

Błędnie przetworzone zdarzenia należy ręcznie dodać do bazy danych. W tym celu należy pobrać z logu eximee-events-errors.log dane zdarzenia, np. :

EventData(origin=SYSTEM, type=PROCESS_PRIORITY_CHANGE, timestamp=1673541340, payload={processInstanceId=f442acfd-877f-11ed-9beb-0242ac120003, uuid=f442acfd-877f-11ed-9beb-0242ac120003, eventDescription=Ustawienie wysokiego priorytetu sprawy, channel=EXIMEE_DASHBOARD, processKey=kredytHipoteczny, username=user0001, params={}}

następnie należy przygotować odpowiedni insert do bazy danych np.:

INSERT INTO case_history_process_history
VALUES (default, 'SYSTEM', to_timestamp(1673541340), 'f442acfd-877f-11ed-9beb-0242ac120003', 'PROCESS_PRIORITY_CHANGE', 'user0001', 'firstName', 'lastName', 'EXIMEE_DASHBOARD', 'Ustawienie wysokiego priorytetu sprawy', '{}', 'f442acfd-877f-11ed-9beb-0242ac120003');

Gdzie:

• firstName należy podmienić na właściwe imię pracownika (np. na podstawie danych z keycloak),
• lastName należy podmienić na właściwe nazwisko pracownika (np. na podstawie danych z keycloak).