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

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

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

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

notification-regulation-structure

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

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

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

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

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

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

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

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

Структура шаблону 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
⛔️ У разі виявлення шахрайських дій щодо вас або помилки кредитора - оскаржіть дані у кредитній історії."

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

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

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>

Структура шаблону 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
⛔️ У разі виявлення шахрайських дій щодо вас або помилки кредитора - оскаржіть дані у кредитній історії."

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

В рамках реалізації рішення, необхідно розширити 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"
  ]
}

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

Для завантаження зформованих/відкорегованих адміністратором шаблонів повідомлень, необхідно розширити пайплайн публікації регламенту етапом '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

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

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

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

Конфігурація типового розширення відправки повідомлення користувачу "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}.

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

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

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

send-single-notification

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

send-multi-notifications

Код опису типового розширення відправки повідомлення користувачу "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
      }
    }
  ]
}