Моделювання регламенту

🌐 Цей документ доступний українською та англійською мовами. Використовуйте перемикач у правому верхньому куті, щоб змінити версію.

1. Моделювання шаблонів повідомлень

1.1. Структура репозиторію регламенту

Для забезпечення вимог по підтримці відправлення повідомлень користувачам, структуру регламенту розширено додатковою директорією <registry-regulation>/notifications:

notification-regulation-structure

Регламент нотифікацій реалізує наступні аспекти адміністрування:

  • notifications/ - Налаштування шаблонів для генерації повідомлення на рівні окремих визначених каналів

1.2. Шаблони повідомлень на рівні окремих каналів зв’язку

Для забезпечення можливостей створення та кастомізації шаблонів повідомлень, як технологію шаблонізації обрано Apache FreeMarker (розширення файлів "*.ftlh" та "*.ftl" для HTML та текстових документів відповідно).

З ціллю подальшого розвитку, в структуру регламенту нотифікацій закладено підтримку шаблонів повідомлень в залежності від наступних каналів зв’язку:

  • inbox - Відправка повідомлень у текстовому вигляді у кабінет громадянина

  • email - Відправка повідомлень у HTML-вигляді електронною поштою

  • diia - Відправка повідомлень у текстовому вигляді через мобільний додаток Дія

1.3. Структура шаблону in-app повідомлення

Типовий шаблон push-повідомлення має наступну структуру:

inbox-notification-structure

  • <template-directory> - Директорія з ресурсами шаблону, яка має унікальне ім’я для заданого каналу зв’язку (email у даному разі)

  • <template-directory>/notification.yml - Мета-дані повідомлення (заголовок повідомлення, тощо.)

  • <template-directory>/notification.ftl - Текстовий Freemarker-шаблон для генерації тіла повідомлення

Приклад файлу мета-даних notification.yml
title: "<Заголовок повідомлення>"

Приклад шаблону notification.ftl:

"У кредитну історію надійшла інформація про новий кредитний договір:\n
дата відкриття - ${dateCredOpen},\nкредитор - ${creditor}.\n
📥 Отримати кредитну історію можна на сайті Українського бюро кредитних історій - ubki.ua.\n
⛔️ У разі виявлення шахрайських дій щодо вас або помилки кредитора - оскаржіть дані у кредитній історії."

1.4. Структура шаблону поштового повідомлення

Типовий шаблон поштового повідомлення має наступну структуру:

email-notification-structure

  • <template-directory> - Директорія з ресурсами шаблону, яка має унікальне ім’я для заданого каналу зв’язку (email у даному разі)

  • <template-directory>/notification.yml - Мета-дані повідомлення (заголовок повідомлення, тощо.)

  • <template-directory>/notification.ftlh - HTML-документ Freemarker-шаблону для генерації тіла повідомлення

  • <template-directory>/css/style.css - "Єдиний CSS-файл стилів, які використовуються в HTML-документі (Приклад: <link rel="stylesheet" href="css/style.css">)

  • <template-directory>/images/*.* - Перелік файлів зображень, які використовуються в HTML-документі (Приклад: <img src="images/image.jpg">)

Приклад файлу мета-даних notification.yml
title: "<Заголовок повідомлення>"
Приклад шаблону notification.ftlh:
<!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>
      дата відкриття - ${dateCredOpen}, кредитор - ${creditor}.
    </p>
</body>
</html>

1.5. Структура шаблону push-повідомлення у мобільний додаток Дія

Типовий шаблон push-повідомлення має наступну структуру:

diia-notification-structure

  • <template-directory> - Директорія з ресурсами шаблону, яка має унікальне ім’я для заданого каналу зв’язку (email у даному разі)

  • <template-directory>/notification.yml - Мета-дані повідомлення (заголовок повідомлення, тип повідомлення, тощо.)

  • <template-directory>/notification.diia - Текстовий шаблон для генерації тіла повідомлення

Приклад файлу мета-даних notification.yml
title: "<Заголовок повідомлення>"
attributes:
  actionType: "<action-type: message>"
  templateType: "<template-type: attention>"
  shortText : "<Короткий опис повідомлення>"
Приклад шаблону notification.diia:
"У кредитну історію надійшла інформація про новий кредитний договір:\n
дата відкриття - {dateCredOpen},\nкредитор - {creditor}.\n
📥 Отримати кредитну історію можна на сайті Українського бюро кредитних історій - ubki.ua.\n
⛔️ У разі виявлення шахрайських дій щодо вас або помилки кредитора - оскаржіть дані у кредитній історії."

1.6. Валідація змін до регламенту шаблонів повідомлень

В рамках реалізації рішення, необхідно розширити CLI-утиліту registry-regulations-validator-cli валідації регламенту додатковими правилами:

  • Валідація відповідності структури шаблону згідно правил окремого каналу зв’язку

  • Перевірка файлів мета-даних шаблонів notification.yml на відповідність JSON-схемі

JSON-схема для валідації шаблону для каналу зв’язку inbox
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "minLength": 1
    }
  },
  "additionalProperties": false,
  "required": [
    "title"
  ]
}
JSON-схема для валідації шаблону для каналу зв’язку email
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "minLength": 1
    }
  },
  "additionalProperties": false,
  "required": [
    "title"
  ]
}
JSON-схема для валідації шаблону для каналу зв’язку diia
{
  "$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"
  ]
}

1.7. Публікація змін до регламенту шаблонів повідомлень

Для завантаження зформованих/відкорегованих адміністратором шаблонів повідомлень, необхідно розширити пайплайн публікації регламенту етапом 'publish-notification-templates' з викликом утиліти notification-template-publisher на кшталт:

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

На даній діаграмі послідовності зображено деталі реалізації кроку завантаження змін та публікації шаблонів повідомлень:

notification-template-publication

2. Моделювання бізнес-процесів з відправленням повідомлень користувачам

Задля спрощення використання можливостей відправки повідомлень користувачам у межах виконання бізнес-процесів, платформа надає Адміністратору регламенту окреме типове розширення "Send User Notification" у каталозі моделювальника.

Канал зв’язку, який буде використано для відправки повідомлення залежить від налаштувань користувача.
send-notification-element-template

2.1. Конфігурація типового розширення відправки повідомлення користувачу "Send User Notification"

Службова назва делегата: SendUserNotificationDelegate

Назва типового розширення: 'Відправка повідомлення користувачу'

Конфігураційний параметр Вхідний/Вихідний Службова назва Тип Опис

Отримувач повідомлення (Recipient)

in

notificationRecipient

string

Унікальний ідентифікатор <username> отримувача повідомлення

Шаблон повідомлення (Notification message template)

in

notificationTemplate

string

Унікальна назва FreeMarker-шаблону для формування тіла повідомлення, яка відповідає назві директорії шаблону згідно структури <registry-regulation>/notifications/<channel>/<template_name>/*.*

Вхідні дані для генерації тіла повідомлення (Notification template model)

in

notificationTemplateModel

map<string, object>

Набір даних для генерації тіла повідомлення на базі шаблона
Для визначення отримувача повідомлення notificationRecipient платформа надає можливість використання службових JUEL-функцій: ${completer('<user-task-id>').userName} або ${initiator().userName}.

2.2. Референтні бізнес-процеси з використанням типового розширення відправки повідомлення

У якості референтних, розглядаються два сценарії моделювання відправки повідомлень у межах виконання бізнес-процесу:

  • Відправка повідомлення користувачу

send-single-notification

  • Відправка повідомлення N користувачам

send-multi-notifications

2.3. Код опису типового розширення відправки повідомлення користувачу "Send User Notification"

{
  "$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
      }
    }
  ]
}