Process event registration

Event registration

This is an event log in which events occurring in the case are recorded chronologically. To enable event registration, set the parameter in the platform configuration: CASE_HISTORY_ENABLED="true"

We register two types of events:

System - performed by users (Customer and Employee):

• case creation,
• taking over a manual step by the user (claim),
• saving a manual step by the user (saving the task - interrupting execution - there is no unClaim here),
• releasing a manual step by the user (unClaim),
• completion of a manual step by the user,
• case completion (end of process),
• change of case priority.

Business - events recorded in History by the process, at moments defined in the process (e.g. in an automatic step or from a form).

A business event has common attributes:

• event type: business,
• event kind,
• assigned person,
• event description,
• structure with event attributes,
• event date.

System Events

Configuration

To use the plugin used to add individual system events to the topic, set the router-api address in the configuration via the ROUTER_ENGINE_CASE_HISTORY_ROUTER_API_URL config, e.g.:

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

Automatic publication of events for types

• PROCESS_START - Process start
• PROCESS_END - Process end
• CLAIM_TASK - User assignment
• UNCLAIM_TASK - User unassignment
• ASSIGNEE_TASK - User assignment by another user
• SEND_USER_TASK - Send user task
• SAVE_TASK - Save task
• PROCESS_PRIORITY_CHANGE - Task priority change

Business Events

Configuration

To register business events, add the dependency to the business application:

events-connector

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

Then add the configuration:

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

where ROUTER_API_URL is the address of the router-api application.

Then in the application code, e.g. in the Camunda task handler, inject the bean CaseHistoryBusinessMessageConnector and call its publish method, passing a BusinessMessage object.

caseHistoryBusinessMessageConnector.publish(BusinessMessage.builder()
        .businessKey(externalTask.getBusinessKey())               // Business process key - required
        .eventCode("Wysyłanie powiadomienia")                     // Event code that will be displayed on the case history list - required
        .processInstanceId(externalTask.getProcessInstanceId())   // Process identifier - required
        .processKey(externalTask.getProcessDefinitionKey())       // Process key - required
        .processName("NazwaProcesu")                              // Process name in Camunda - required
        .eventDescription("Opis zadania")                         // Event description that will be displayed on the case history list - optional
        .userId("123456")                                         // User who performed the given action. The value will be displayed on the case history list - required
        .params(Map.of(                                           // Business parameters that will be displayed in the Case History tab, in the event details - optional                                                          
               "Numer telefonu", externalTask.getVariable("authorizationPhoneNumber"),
               "Priorytet", StringUtils.defaultString(externalTask.getVariable("priority"), "BRAK"))
        )
        .build());

Retrieving information for system events and business events

In the case of the event "releasing a manual step by the user" (unclaim), when called outside Router 2 (i.e. directly via the Camunda API), you need to add handling for a business event that intercepts the unclaim call.

To properly register the event channel, add the variable to each request router_channel:

Figure 5. Session variable "router_channel"

Figure 6. Input parameter "router_channel"

Kafka

Kafka configuration for process event registration:

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

In the Kafka environment, the 'all' topic was created. All events, including those from process event registration, are sent to the new topic. The router-api application fetches data from the all topic for the case history tab in Eximee Dashboard.

Example event object that goes to the queue:

{
  "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": {
            "Label 1": "Value 1",
            "Label 2": "Value 2"
        }
   }
}

Error handling

In the event of an error while fetching an event, error information is written to the log eximee-events-errors.log.

Example error entry:

[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=Setting a high case priority, 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

where:

• [router2-api-docker] - container identifier that reported the error,
• key - event key,
• offset - message index in Kafka,
• value - processed object,
• topic - Kafka topic from which the event was consumed.

Diagnostic endpoint for errors while fetching case history events

An endpoint was created to check whether there is an entry in the current error file for events:

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

Response: false - the file is empty true - there are some errors in the file

Retrying errors

Incorrectly processed events must be manually added to the database. For this purpose, retrieve from the log eximee-events-errors.log the event data, e.g.:

EventData(origin=SYSTEM, type=PROCESS_PRIORITY_CHANGE, timestamp=1673541340, payload={processInstanceId=f442acfd-877f-11ed-9beb-0242ac120003, uuid=f442acfd-877f-11ed-9beb-0242ac120003, eventDescription=Setting a high case priority, channel=EXIMEE_DASHBOARD, processKey=kredytHipoteczny, username=user0001, params={}}

then prepare the appropriate insert into the database, e.g.:

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', 'Setting a high case priority', '{}', 'f442acfd-877f-11ed-9beb-0242ac120003');

Where:

• firstName should be replaced with the employee's correct first name (e.g. based on data from Keycloak),
• lastName should be replaced with the employee's correct last name (e.g. based on data from Keycloak).