Auditing and event logging

🌐 This document is available in both English and Ukrainian. Use the language toggle in the top right corner to switch between versions.

1. Approach overview

All events of sending messages to users by the system are recorded in the audit log with full context. It is necessary to expand the audit subsystem as follows to meet the requirement:

  • Enter a separate category of audit events for recording business operations:

    • EVENT_TYPE = SYSTEM_EVENT

  • Expand the list of official operations:

    • SEND_USER_NOTIFICATION

You can read more about the design of the "Audit Log" subsystem by link
An example of settings for publishing audit events via a Kafka topic (on the example of using the ddm-starter-audit library)
audit:
  kafka:
    topic: audit-events
    schemaRegistryUrl: http://kafka-schema-registry:8081

2. Structure of an audit event

Below is the audit event structure and its correspondence to the structure and values of the message received via the Kafka topic about the need to send a notification to the user.

Attribute Value

timestamp

now()

application_name

"notification-service"

name

"SEND_USER_NOTIFICATION"

type

"SYSTEM_EVENT"

request_id

<MDC.traceId>

source_system

<context.system>

source_application

<context.application>

source_business_process

<context.businessProcess>

source_business_process_definition_id

<context.businessProcessDefinitionId>

source_business_process_instance_id

<context.businessProcessInstanceId>

source_business_activity

<context.businessActivity>

source_business_activity_id

<context.businessActivityInstanceId>

context

<JSON-representation of the details of the operation and the result of its execution>

2.1. Audit event context structure for communication channels

2.1.1. Email channel

JSON-representation of event details to capture the sending of a mail message
{
  "notification": {
    "channel:": "email",
    "subject": "<Notification header>",
    "message": "<Notification>",
    "recipient": {
      "id": "<User ID - optional>",
      "email": "<User email address>"
    }
  }
}

2.1.2. Inbox channel

JSON-presentation of event details for recording the sending of a message in the portal inbox
{
  "notification": {
    "channel:": "inbox",
    "subject": "<Notification header>",
    "message": "<Notification>",
    "recipient": {
      "id": "<User ID>"
    }
  }
}

2.1.3. Citizen-facing mobile channels

This functionality is specific to the Ukrainian implementation and may not apply or function as described in other contexts or regions. Please consult the local guidelines or documentation if you are implementing this outside Ukraine.

In Ukraine citizen-facing solutions represented via the "Diia" service. The Platform has notification template supported for interacting with this service via appropriate notification channel.

Example. JSON-representation of event details to capture the sending of a message to the citizen-facing mobile services 
{
  "notification": {
    "channel:": "diia",
    "externalTemplateId": "<TemplateId>",
    "templateName": "<Template name>",
    "distributionId": "<Distribution Id>",
    "recipient": {
      "id": "<User Id>",
      "rnokpp": "<Registration number of the taxpayer’s account card>",
      "parameters": [
        {
          "key": "<key>",
          "value": "<value>"
        }
      ]
    }
  }
}