Налаштування відправлення in-app повідомлень користувачам

1. Загальний опис

Для можливості надсилати текстові повідомлення до скриньки користувача у Кабінеті отримувача послуг, адміністратор регламенту повинен спочатку змоделювати відповідний шаблон для каналу зв’язку inbox та додати його в структуру регламенту реєстру.

2. Налаштування регламенту

Репозиторій розгортання регламенту registry-regulations розширено базовою директорією inbox/business-process-notification-template. Ця директорія містить файли шаблону in-app-повідомлень, які користувач може отримувати через канал зв’язку inbox в особистому кабінеті.

Адміністратор регламенту може змоделювати та додати будь-яку кількість шаблонів до структури регламенту, залежно від бізнес-потреб.

Шаблон business-process-notification-template — це базовий шаблон у структурі регламенту для цього каналу зв’язку. Шаблонів може бути багато. Назва кожного шаблону в рамках одного каналу зв’язку має бути унікальною.

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

Шлях до шаблону виглядає наступним чином: 
registry-regulations/notifications/inbox/<template-directory>
Типовий шаблон in-app-повідомлень має наступну структуру:
email-notification-structure

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

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

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

  • <template-directory>/notification.yml — Конфігураційний файл із метаданими шаблону, що містить заголовок повідомлення.

    Приклад 2. Конфігураційний файл із заголовком повідомлення
    title: "Повідомлення від УБКІ!"
    Для прикладу використано шаблон повідомлення від УБКІ — Українське бюро кредитних історій.

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

Кожний опублікований шаблон повідомлення повинен мати унікальну назву, яку надалі можна використовувати при моделюванні бізнес-процесу.

3. Моделювання відправлення in-app повідомлень

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

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

Після розгортання регламенту, і публікації шаблону push-сповіщення до сховища, моделювальник бізнес-процесів може використовувати унікальну назву шаблону у полі Notification message template при моделюванні кроку відправлення push-повідомлення користувачу.

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

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

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

  1. Перейдіть до інтерфейсу моделювання бізнес-процесів.

  2. Створіть Send Task.

    e mail notification 02

  3. На панелі налаштувань справа натисніть кнопку Open Catalog та оберіть шаблон (template) делегата — Send User Notification. Для підтвердження натисніть Apply.

    e mail notification 03

  4. Виконайте подальші налаштування:

    • У полі Name вкажіть назву задачі. Наприклад, Відправлення in-app-повідомлення користувачу.

    • У полі Recipient вкажіть унікальний ідентифікатор — <username> отримувача повідомлення. Наприклад, ${initiator().userName}.

      У цьому випадку зазначено ім’я ініціатора процесу як реципієнта — ${initiator().userName}. Також можна вписати, наприклад виконавця задачі, вказавши ${completer('<taskDefinitionId>').userName}, де <taskDefinitionId> — ідентифікатор користувацької задачі.

    • У полі Subject вкажіть текстову назву теми повідомлення. Наприклад, Notification successfully generated.

    • У полі Notification message template вкажіть унікальну назву шаблону для формування тіла повідомлення, яка відповідає назві директорії наявного шаблону у регламенті (наприклад, business-process-notification-template).

    • У полі Notification template model вкажіть змінну, яка використовуватиметься для опрацювання шаблону — ${templateModel}.

      inbox template 1

    Користувач зможе отримувати сповіщення до скриньки Кабінету отримувача послуг у розділі Повідомлення.

Перегляньте сторінку Відправлення inbox-повідомлень користувачам для отримання деталей.

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

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

inbox template 2

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

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

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

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

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

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

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

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

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

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

Ви можете самостійно переглянути фіксацію подій відправлення повідомлень у логах бази даних audit, під’єднатися до якої можливо за інструкцією:
Приклад 3. Аудит подій відправлення inbox-повідомлень
Фіксація події успішного відправлення повідомлення у БД audit 
{
  "result": "SUCCESS",
  "notification": {
    "channel": "inbox",
    "subject": "Повідомлення від УБКІ!",
    "message": "У кредитну історію надійшла інформація про новий кредитний договір:\nдата відкриття - Wed Jul 26 12:54:51 UTC 1978, кредитор - auto-user-notification-f278366.\nОтримати кредитну історію можна на сайті Українського бюро кредитних історій - ubki.ua.\nУ разі виявлення шахрайських дій щодо вас або помилки кредитора - оскаржіть дані у кредитній історії.",
    "recipient": {
      "id": "auto-user-notification-f",
      "email": null
    }
  },
  "delivery": {
    "channel": "inbox",
    "status": "SUCCESS",
    "failureReason": null
  },
  "action": "SEND_USER_NOTIFICATION",
  "step": "AFTER"
}

  • Параметр result вказує на результат надсилання повідомлення.

  • Параметр channel вказує, який канал зв’язку із користувачем використано.

  • Параметр message — тіло повідомлення із бізнес-даними, сформоване на базі шаблону.

  • Атрибут recipient показує інформацію про отримувача повідомлення.

  • Атрибут 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": "inbox",
    "status": "FAILURE",
    "failureReason": "Notification template inbox-template-ubki111 not found"
  },
  "action": "SEND_USER_NOTIFICATION",
  "step": "AFTER"
}

  • Параметр result вказує на результат надсилання повідомлення.

  • Параметр context надає деталі про бізнес-процес, в рамках якого змодельовано відправлення повідомлення, а також його складові.

  • Параметр templateName вказує, який шаблон було використано для надсилання повідомлення.

  • Масив recipients показує інформацію про отримувачів повідомлення, а також канали зв’язку.

  • Атрибут delivery відображає статус доставлення за відповідним каналом зв’язку та причину помилки.