Налаштування відправлення push-повідомлень у застосунок "Дія"

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

Для налаштування функції відправлення push-сповіщень користувачам у мобільний застосунок "Дія", користувач має спочатку підтвердити, тобто авторизувати канал зв’язку diia за допомогою OTP-коду. Для підтвердження використовується окремий шаблон channel-confirmation, який адміністратор регламенту повинен змоделювати.

Також для того, щоб мати змогу отримувати повідомлення, користувач має активувати канал зв’язку "Дія" у профілі Кабінету отримувача послуг.

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

Базовий репозиторій розгортання регламенту registry-regulations розширено директорією business-process-notification-template, яка містить шаблон push-повідомлення, яке надсилатиметься користувачам у мобільний застосунок "Дія".

Адміністратор регламенту повинен змоделювати та додати шаблон формування push-повідомлення на рівні каналу зв’язку diia до структури регламенту.

Типовий шаблон push-повідомлень у застосунок "Дія" має наступну структуру:
email-notification-structure
Шаблон business-process-notification-template — це базовий шаблон у структурі регламенту для цього каналу зв’язку. Шаблонів може бути багато. Назва кожного шаблону в рамках одного каналу зв’язку має бути унікальною.
Шлях до шаблону виглядає наступним чином: 
registry-regulations/notifications/diia/business-process-notification-template
Директорія business-process-notification-template містить 2 файли:

  • notification.diia — це текстовий формат шаблону повідомлення з плейсхолдером для відображення даних із бізнес-процесу.

Приклад 1. Шаблон із плейсхолдером для відображення даних із бізнес-процесу
Процес: {processName} успішно виконано

{processName} — плейсхолдер.

  • notification.yml — Конфігураційний файл з метаданими шаблону.

Приклад 2. Конфігураційний файл з метаданими шаблону
title: "Процес успішно виконано"
attributes:
  actionType: "message"
  templateType: "attention"
  shortText : "Процес успішно виконано"
Обов’язкові атрибути:

  • title — Заголовок повідомлення. Вкажіть будь-який текст за бажанням.

  • actionType — Тип дії.

    Необхідно вказати саме тип actionType: "message", інакше "Дія" не зможе приймати повідомлення.

  • templateType — Тип шаблону.

    Необхідно вказати саме тип templateType: "attention", інакше "Дія" не зможе приймати повідомлення.

  • shortText — Короткий зміст повідомлення. Вкажіть будь-який текст за бажанням.

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

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

3. Моделювання відправлення push-сповіщення у застосунок "Дія"

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

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 вкажіть назву задачі. Наприклад, Відправлення push-повідомлення користувачу.

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

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

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

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

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

      diia template 2

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

Перегляньте сторінку Отримання push-повідомлень з OTP-кодом у застосунку "Дія" для отримання деталей.

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

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

diia template 1

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

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

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

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

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

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

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

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

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

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

Ви можете самостійно переглянути фіксацію подій відправлення повідомлень у логах бази даних audit, під’єднатися до якої можливо за інструкцією:
Приклад 3. Аудит подій відправлення push-нотифікацій у "Дію"
Фіксація події успішного відправлення повідомлення у БД audit 
{
  "result": "SUCCESS",
  "notification": {
    "channel": "diia",
    "externalTemplateId": "71c7c3f638b1f5dcfae41ba7b5d4ea130b42ee6ac12323b11f900956d97ba071fbdb3f6a1a1d474682bae2e1813daaf603234cfb958a4e50242f0865fab90d90",
    "templateName": "inbox-template-ubki",
    "distributionId": "05e31e36ba74323f699cbf0174bb47f9daf1291e9d4dc6556ba3b261b7b94cd0880d3af14122872465cd03d8ba860f0ebbea89940b51e572b53f8d2f6230f469",
    "recipient": {
      "rnokpp": "1010101014",
      "id": "auto-user-citizen",
      "parameters": [
        {
          "key": "dateCredOpen",
          "value": "inbox-template-ubki"
        },
        {
          "key": "creditor",
          "value": "inbox-template-ubki"
        }
      ]
    }
  },
  "delivery": {
    "channel": "diia",
    "status": "SUCCESS",
    "failureReason": null
  },
  "action": "SEND_USER_NOTIFICATION",
  "step": "AFTER"
}

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

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

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

  • Атрибут recipient показує інформацію про отримувача повідомлення, а саме його ID та РНОКПП (ідентифікаційний номер).

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

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

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

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

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

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