Registry regulations modeling

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

1. Message template modeling

1.1. Regulations repository structure

To meet the requirements for supporting message delivery to users, the regulations structure has been expanded with an additional directory <registry-regulation>/notifications:

notification-regulation-structure

The notification regulation encompasses the following administration aspects:

  • notifications/ - Configuration of templates for message generation at the level of individual designated channels

2. Channel-specific message templates

To facilitate the creation and customization of message templates, Apache FreeMarker has been chosen as the templating technology (using ".ftlh" and ".ftl" extensions for HTML and text documents, respectively).

With the aim of further development, the regulations notification structure incorporates support for message templates depending on the following communication channels:

  • inbox - Sending text-based messages to the citizen portal

  • email - Sending HTML-formatted messages via email

  • diia - Sending text-based messages through the mobile application "Diia" (Ukrainian citizen-facing solution, UA-specific)

2.1. In-app notification template structure

A typical push notification template has the following structure:

inbox-notification-structure

  • <template-directory> - Directory containing template resources with a unique name for the specified communication channel (email in this case)

  • <template-directory>/notification.yml - Message metadata (message title, etc.)

  • <template-directory>/notification.ftl - Textual Freemarker template for generating the message body

Example notification.yml metadata file:
title: "<Message title>"

Example notification.ftl template:

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. 
"Information about a new credit agreement has been added to your credit history:\n
Opening date - ${dateCredOpen},\nCreditor - ${creditor}.\n
📥 You can obtain your credit history on the website of the Ukrainian Credit Bureau - ubki.ua.\n
⛔️ In case of fraudulent actions concerning you or creditor errors - "

2.2. Email message template structure

A typical email message template follows this structure:

email-notification-structure

  • <template-directory> - Directory containing template resources with a unique name for the specified communication channel (email in this case)

  • <template-directory>/notification.yml - Message metadata (message title, etc.)

  • <template-directory>/notification.ftlh - HTML document Freemarker template for generating the message body

  • <template-directory>/css/style.css - Single CSS style file used in the HTML document (Example: <link rel="stylesheet" href="css/style.css">)

  • <template-directory>/images/*.* - List of image files used in the HTML document (Example: <img src="images/image.jpg">)

Example notification.yml metadata file:
title: "<Message title>"
Example notification.ftlh template:
<!DOCTYPE html>
<html>
<head>
    <link rel="stylesheet" href="css/style.css">
</head>
<body>
    <div class="center">
        <img src="images/image.jpg" class="trinity"/>
    </div>
    <p>
      opening date - ${dateCredOpen}, creditor - ${creditor}.
    </p>
</body>
</html>

2.3. Validation of changes to message template regulations

As part of the solution implementation, it’s necessary to enhance the registry-regulations-validator-cli CLI utility for validating regulations with additional rules:

  • Validation of template structure conformity according to specific communication channel rules.

  • Checking notification.yml metadata files for compliance with JSON schema

JSON schema for validating templates for the inbox communication channel:
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "minLength": 1
    }
  },
  "additionalProperties": false,
  "required": [
    "title"
  ]
}
JSON schema for validating template for the email communication channel:
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "minLength": 1
    }
  },
  "additionalProperties": false,
  "required": [
    "title"
  ]
}
JSON schema for validating template for the diia (Ukrainian citizen-facing solution, UA-specific) communication channel:
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "minLength": 1
    },
    "attributes": {
      "type": "object",
      "properties": {
        "actionType": {
          "type": "string",
          "enum": [
            "message"
          ]
        },
        "templateType": {
          "type": "string",
          "enum": [
            "attention"
          ]
        },
        "shortText": {
          "type": "string",
          "minLength": 1
        }
      },
      "additionalProperties": false,
      "required": [
        "actionType", "templateType", "shortText"
      ]
    }
  },
  "additionalProperties": false,
  "required": [
    "title"
  ]
}

2.4. Publishing changes to the message template regulations

To upload the generated/adjusted message templates by the administrator, it’s necessary to expand the publication pipeline of regulations with the 'publish-notification-templates' stage, calling the notification-template-publisher utility as follows:

java -jar
  -NOTIFICATION_SERVICE_URL=<notification-service.url>
  /home/jenkins/notification-template-publisher/notification-template-publisher.jar --notification_templates=notifications/templates

The sequence diagram illustrates the implementation details of the step for uploading changes and publishing message templates:

notification-template-publication

3. Modeling business processes with user message sending

For simplifying the utilization of user message sending capabilities within business process execution, the platform provides the Regulations administrator with a distinct default extension named "Send User Notification" in the modeler catalog.

The communication channel used for sending the message depends on user settings.
send-notification-element-template

3.1. Configuration of the default "Send User Notification" extension

Delegate technical name: SendUserNotificationDelegate

Default extension name: 'Send User Notification'

Configuration parameter Input/Output Technical name Type Description

Notification recipient (Recipient)

in

notificationRecipient

string

Unique identifier <username> of the message recipient

Notification message template (Notification message template)

in

notificationTemplate

string

Unique name of the FreeMarker template used to generate the message body. It corresponds to the template directory name within the structure <registry-regulation>/notifications/<channel>/<template_name>/*.*

Input data for message body generation (Notification template model)

in

notificationTemplateModel

map<string, object>

Dataset used to generate the message body based on the template
To define the notificationRecipient, the platform offers the use of built-in JUEL functions: ${completer('<user-task-id>').userName} або ${initiator().userName}.

3.2. Reference business processes using the default extension for sending a message

Two modeling scenarios involving message sending within a business process execution are considered as references:

  • Sending a notification to a user

send-single-notification

  • Sending a Message to N Users

send-multi-notifications

3.3. Code description of the standard "Send User Notification" extension

{
  "$schema": "https://unpkg.com/@camunda/element-templates-json-schema/resources/schema.json",
  "name": "Send User Notification",
  "id": "sendUserNotification",
  "appliesTo": [
    "bpmn:SendTask"
  ],
  "properties": [
    {
      "label": "Implementation Type",
      "type": "Hidden",
      "value": "${sendUserNotificationDelegate}",
      "editable": false,
      "binding": {
        "type": "property",
        "name": "camunda:delegateExpression"
      }
    },
    {
      "label": "Recipient",
      "description": "Notification recipient username <br/>(${initiator().userName or completer('taskDefinitionId').userName})",
      "type": "String",
      "binding": {
        "type": "camunda:inputParameter",
        "name": "notificationRecipient"
      },
      "constraints": {
        "notEmpty": true
      }
    },
    {
      "label": "Notification message template",
      "description": "Notification message template <br/>(<registry-regulation>/notifications/<channel>/<template_name>/*.*)",
      "type": "String",
      "binding": {
        "type": "camunda:inputParameter",
        "name": "notificationTemplate"
      },
      "constraints": {
        "notEmpty": true
      }
    },
    {
      "label": "Notification template model",
      "description": "Notification template model <br/>(${templateModel} variable to be used for template processing)",
      "type": "String",
      "binding": {
        "type": "camunda:inputParameter",
        "name": "notificationTemplateModel"
      },
      "constraints": {
        "notEmpty": true
      }
    }
  ]
}