# 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**

```xml
<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.

```java
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")                                         // Użytkownik, który wykonał daną czynność. Wartość będzie wyświetlana na liście historii sprawy - 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());
```

## Pobieranie informacji do zdarzeń systemowych i zdarzeń biznesowych

Do właściwego działania rejestrowania zdarzeń systemowych i biznesowych należy również, na wniosku startującym proces, dodać zmienną **router\_user\_id** i dodać ją do parametrów wejściowych:

<figure><img src="https://1082717226-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F2CssJT0zIo4SJQLbSZ6l%2Fuploads%2Fgit-blob-b7c19dc659e3c8e2a31576b2a8c22243d03e2770%2Frejestracja_zdarzen_procesu_zmienna_sesyjna_router_user_id.png?alt=media" alt=""><figcaption><p><em><strong>Ilustracja 1.</strong> Zmienna sesyjna "router_user_id"</em></p></figcaption></figure>

<figure><img src="https://1082717226-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F2CssJT0zIo4SJQLbSZ6l%2Fuploads%2Fgit-blob-8803fec7bd02db66068981034488e83050d659cb%2Frejestracja_zdarzen_procesu_parametr_wejsciowy_router_user_id.png?alt=media" alt=""><figcaption><p><em><strong>Ilustracja 2.</strong> Parametr wejściowy "router_user_id"</em></p></figcaption></figure>

a na wnioskach w ramach procesu dodać zmienną **router\_claim\_user\_id** i dodać ją do parametrów wejściowych:

<figure><img src="https://1082717226-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F2CssJT0zIo4SJQLbSZ6l%2Fuploads%2Fgit-blob-6171379ce98c50440b290dbad72fe05969a78778%2Frejestracja_zdarzen_procesu_zmienna_sesyjna_router_claim_user_id.png?alt=media" alt=""><figcaption><p><em><strong>Ilustracja 3.</strong> Zmienna sesyjna "router_claim_user_id"</em></p></figcaption></figure>

<figure><img src="https://1082717226-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F2CssJT0zIo4SJQLbSZ6l%2Fuploads%2Fgit-blob-e10ee1054523c25a70acbc84798630d00e213c82%2Frejestracja_zdarzen_procesu_parametr_wejsciowy_router_claim_user_id.png?alt=media" alt=""><figcaption><p><em><strong>Ilustracja 4.</strong> Parametr wejściowy "router_claim_user_id"</em></p></figcaption></figure>

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.

Dodatkowo w celu właściwego rejestrowania kanału zdarzenia, należy dodać na każdym wniosku zmienną **router\_channel** (analogicznie jak w przypadku **router\_user\_id** i **router\_claim\_user\_id**):

<figure><img src="https://1082717226-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F2CssJT0zIo4SJQLbSZ6l%2Fuploads%2Fgit-blob-f844b15b0ba08fb77b855ea972d79a6f56239143%2Frejestracja_zdarzen_procesu_zmienna_sesyjna_router_channel.png?alt=media" alt=""><figcaption><p><em><strong>Ilustracja 5.</strong> Zmienna sesyjna "router_channel"</em></p></figcaption></figure>

<figure><img src="https://1082717226-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F2CssJT0zIo4SJQLbSZ6l%2Fuploads%2Fgit-blob-d0b9a81fa49fbb335bba011fa0270e264e51027a%2Frejestracja_zdarzen_procesu_parametr_wejsciowy_router_channel.png?alt=media" alt=""><figcaption><p><em><strong>Ilustracja 6.</strong> Parametr wejściowy "router_channel"</em></p></figcaption></figure>

## 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ę:

```js
{
  "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. :

```js
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.:

```js
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).