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

ЗМІСТ

1. Передумови
2. Налаштування шаблону повідомлення
3. Моделювання бізнес-процесів
4. Логування відправлення повідомлень у журналі аудиту

1. Передумови

Платформа підтримує відправлення електронних повідомлень з використанням SMTP-протоколу для комунікації та однієї з наступних опцій налаштувань поштового сервера, залежно від вимог реєстру:

Поштовий сервер платформи;
Зовнішній поштовий сервер.

Попередньо необхідно виконати налаштування каналів зв’язку для відправки повідомлень користувачам реєстру.

Детальну інформацію щодо налаштування відправки повідомлень можна отримати за посиланнями:

Відправка повідомлень системою можлива лише зареєстрованим користувачам.

2. Налаштування шаблону повідомлення

Для реалізації функціональності відправки email-повідомлень користувачам кабінету через електронну пошту, необхідно створити шаблон повідомлення, що буде використовуватися при моделюванні бізнес-процесу.

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

Детальну інформацію щодо Apache FreeMarker можливо отримати за посиланням:

https://freemarker.apache.org/

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

<template-directory> — директорія з ресурсами шаблону, яка має унікальне ім’я для заданого каналу зв’язку;
<template-directory>/css/style.css — єдиний CSS-файл стилів, які використовуються в HTML-документі (Приклад: <link rel="stylesheet" href="css/style.css">);
<template-directory>/image/*.* — перелік файлів зображень, які використовуються в HTML-документі (Приклад: <img src="images/image.jpg">);

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

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

<!DOCTYPE html>
<html lang="uk">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=0"/>
    <link rel="stylesheet" href="style.css">
</head>
<body>
    <div class="header">
        <div class="logo-wrap">
            <img src="image/trident.jpg" alt="Diia" class="logo">
        </div>
        <div class="platform-name">Платформа<br>реєстрів</div>
    </div>
    <div class="main">
        Процес: ${processName} успішно виконаний
    </div>
    <div class="footer">
        <br>
        Адреса чи службова інформація
    </div>
</body>
</html>

<template-directory>/notification.yml — Конфігураційний файл з метаданими для відправлення поштового повідомлення.
Приклад 1. Конфігураційний файл з метаданими для відправлення поштового повідомлення
title: "Процес успішно виконаний"

3. Моделювання бізнес-процесів

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

відправлення повідомлень одному користувачу;
відправлення повідомлень багатьом користувачам.

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

Для моделювання бізнес-процесу використовується типове розширення для задач на відправлення повідомлення (Send Task) — Send User Notification.

Розширення Send User Notification — делегат для відправлення повідомлень отримувачам послуг електронною поштою, з використанням заданого шаблону в HTML-вигляді.

Перед налаштуванням шаблону в Сamunda Modeler переконайтеся, що папка із застосунком resources → element-templates містить sendUserNotification.json

Для налаштування шаблону виконайте наступні кроки:

Створіть Send Task.
На панелі налаштувань справа натисніть кнопку Open Catalog та оберіть шаблон (template) делегата — Send User Notification. Для підтвердження натисніть Apply.
Виконайте подальші налаштування:
- У полі name вкажіть назву задачі (наприклад, Відправка email користувачу).
- У полі Recipient вкажіть унікальний ідентифікатор — <username> отримувача повідомлення (наприклад, ${initiator().userName}).
- У полі Subject вкажіть текстову назву теми повідомлення (наприклад, Email successfully generated).
- У полі Notification message template вкажіть унікальну назву шаблону для формування тіла повідомлення, яка відповідає назві директорії наявного шаблону у регламенті (наприклад, business-process-notification-template).
- У полі Notification template model — вкажіть набір даних для генерації тіла повідомлення на базі шаблону (наприклад, ${templateModel}).

3.2. Відправка повідомлень багатьом користувачам

Для відправлення повідомлень багатьом користувачам моделювання бізнес-процесу відбувається за аналогією з моделюванням бізнес-процесу відправки повідомлення одному користувачу, за виключенням використання функції мультиекземпляра (Multi Instance). Ця функція дозволяє виконати одночасне відправлення повідомлень усім зазначеним користувачам із масиву.

e mail notification 07

У полі Collection вкажіть масив користувачів, що отримані за атрибутами із сервісу Keycloak. У цьому випадку масив записаний до змінної ${usersByAttributes}, яку і вказуємо у полі.

У нашому прикладі вказана змінна ${usersByAttributes}, до якої попередньо збережений масив імен (username) користувачів у бізнес-процесі. Також імена отримувачів повідомлення можна задати простими константами через кому. Наприклад, username1,username2,username3.

У полі Element Variable зазначте локальну змінну екземпляра під заданим іменем.

Процес відправки повідомлення не блокує основний потік виконання бізнес-процесу та виконується асинхронно.

Детальніше ознайомитися з функцією Multi Instance ви можете за посиланням:

Multi-Instance

З метою отримання списку користувачів (отримувачів послуг) для відправки їм повідомлень, доступне типове розширення для сервісних задач:

Делегат getCitizenUsersByAttributesFromKeycloak — використовується для пошуку користувачів Кабінету отримувачів послуг у Keycloak за їх атрибутами.

Детальну інформацію щодо налаштування делегата можна отримати за посиланням:

Пошук отримувачів послуг у Keycloak за їх атрибутами

4. Логування відправлення повідомлень у журналі аудиту

Події успішного, або неуспішного відправлення повідомлень користувачу на електронну пошту логується в журналі аудиту та зберігається у базі даних audit.

Приклад 2. Аудит подій відправлення поштових повідомлень

Фіксація події успішного відправлення повідомлення у БД audit

{
  "result": "SUCCESS",
  "notification": {
    "channel": "email",
    "subject": "Повідомлення від УБКІ!",
    "message": "<!DOCTYPE html>\n<html lang=\"uk\"> \n <head> \n  <meta charset=\"UTF-8\" /> \n  <meta name=\"viewport\" content=\"width=device-width, initial-scale=1, maximum-scale=1, user-scalable=0\" />  \n  <style>body {\n    margin: 0;\n    padding: 0;\n    line-height: 1;\n    font-family: 'e-Ukraine', Verdana, sans-serif;\n}\n\n.header {\n    padding: 0 48px;\n    margin: 32px 0;\n    color: #000;\n    font-size: 16px;\n}\n\n.logo-wrap {\n    float: left;\n    margin-right: 16px;\n}\n\n.logo {\n    width: 48px;\n    height: 48px;\n}\n\n.platform-name {\n    font-size: 16px;\n    line-height: 24px;\n}\n\n.main {\n    padding: 0 48px;\n    margin: 48px 0;\n    color: #000;\n    font-size: 16px;\n    line-height: 24px;\n}\n\n.main-title {\n    margin-bottom: 24px;\n    font-size: 24px;\n    line-height: 28px;\n}\n\n.footer {\n    padding: 16px 48px 80px;\n    background: #000;\n    color: #fff;\n    font-size: 12px;\n    line-height: 16px;\n}\n</style>\n </head> \n <body>  \n  <div class=\"main\">\n    У кредитну історію надійшла інформація про новий кредитний договір: дата відкриття - Wed Jul 26 12:54:51 UTC 1978, кредитор - auto-user-notification-f278366. Отримати кредитну історію можна на сайті Українського бюро кредитних історій - ubki.ua. У разі виявлення шахрайських дій щодо вас або помилки кредитора - оскаржіть дані у кредитній історії. \n  </div> \n  <div class=\"footer\"> \n   <br /> Адреса чи службова інформація \n  </div>  \n </body>\n</html>",
    "recipient": {
      "id": "auto-user-notification-f",
      "email": "auto-user-notification-f@inbucket.inbucket.svc.cluster.local"
    }
  },
  "delivery": {
    "channel": "email",
    "status": "SUCCESS",
    "failureReason": null
  },
  "action": "SEND_USER_NOTIFICATION",
  "step": "AFTER"
}

Параметр result вказує на результат надсилання повідомлення.
Параметр channel вказує, який канал зв’язку із користувачем використано.
Параметр subject вказує тему повідомлення.
Атрибут recipient показує інформацію про отримувача повідомлення, а саме його ID та Email.
Атрибут delivery відображає статус доставлення за відповідним каналом зв’язку.

Фіксація події неуспішного відправлення повідомлення у БД audit

{
  "result": "FAILURE",
  "notification": {
    "context": {
      "system": "Low-code Platform",
      "application": "ddm-bpm",
      "businessProcess": "bpmn-send-inbox-with-form",
      "businessProcessDefinitionId": "bpmn-send-inbox-with-form:2:1f54abab-65b2-11ed-8fda-0a580a822841",
      "businessProcessInstanceId": "b84ceb8f-65b8-11ed-8fda-0a580a822841",
      "businessActivity": "Activity_0l2g5sf",
      "businessActivityInstanceId": "Activity_0l2g5sf:b84e9948-65b8-11ed-8fda-0a580a822841"
    },
    "notification": {
      "title": null,
      "templateName": "inbox-template-ubki111",
      "ignoreChannelPreferences": false
    },
    "recipients": [
      {
        "id": "auto-user-citizen",
        "channels": [
          {
            "channel": "diia",
            "email": null,
            "rnokpp": "1010101014"
          },
          {
            "channel": "email",
            "email": "auto1-user-citizen@inbucket.inbucket.svc.cluster.local",
            "rnokpp": null
          }
        ],
        "parameters": {
          "dateCredOpen": "inbox-template-ubki",
          "creditor": "inbox-template-ubki"
        }
      }
    ]
  },
  "delivery": {
    "channel": "email",
    "status": "FAILURE",
    "failureReason": "Notification template inbox-template-ubki111 not found"
  },
  "action": "SEND_USER_NOTIFICATION",
  "step": "AFTER"
}

Параметр result вказує на результат надсилання повідомлення.
Параметр context надає деталі про бізнес-процес, в рамках якого змодельовано відправлення повідомлення, а також його складові.
Параметр templateName вказує, який шаблон було використано для надсилання повідомлення.
Масив recipients показує інформацію про отримувачів повідомлення, а також канали зв’язку.
Атрибут delivery відображає статус доставлення за відповідним каналом зв’язку та причину помилки.