Пошук користувачів реєстру за атрибутами: Search registry users by attributes

Цей документ надає інструкції щодо використання інтеграційного розширення для пошуку користувачів у реєстрі за атрибутами через REST API.

1. Загальна інформація

Інтеграційне розширення Search registry users by attributes надає змогу виконувати пошук користувачів у реєстрі за різними атрибутами, сприяючи оптимізації процесів взаємодії з користувачами.

Таблиця 1. Короткі відомості про делегат
Назва Пояснення

Бізнес-назва інтеграційного розширення

Search registry users by attributes

Службова назва інтеграційного розширення

${searchRegistryUsersByAttributes}

Назва файлу у бібліотеці розширень

searchRegistryUsersByAttributes.json

2. Перед початком

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

При моделюванні бізнес-процесів із використанням сторонніх застосунків, важливо інтегрувати каталог типових розширень з нашого репозиторію. Завітайте до business-process-modeler-extensions, щоб завантажити необхідні файли. Наприклад, для таких інструментів, як Camunda Modeler, у вашій теці /element-templates мають бути включені відповідні JSON-файли. Для детальних інструкцій, будь ласка, перегляньте Встановлення типових розширень.

3. Налаштування делегата

Делегат Search registry users by attributes призначений для використання у сервісних завданнях (Service Task) бізнес-процесу. Він дозволяє виконати пошук користувачів у реєстрі за заданими атрибутами. Keycloak API отримує GET-запити із заданими параметрами та повертає масив імен (username) користувачів, які надалі можна використати у бізнес-процесі.

Наразі обов’язковими атрибутами для всіх реєстрів є edrpou, drfo та fullName.

Реєстри можуть також використовувати довільні атрибути. Наприклад, hierachy_code.

Зверніть увагу, що залежно від контексту вашої бізнес-логіки, довільний атрибут може бути обов’язковим. Наприклад, коли ви використовуєте ієрархічну модель доступу до даних. Більш детально про це — див. Ієрархічна модель.

3.1. Налаштування сервісного завдання

  1. Створіть завдання типу Service Task у вашому бізнес-процесі.

  2. Назвіть завдання, наприклад, Отримання переліку посадових осіб реалма.

  3. Застосуйте шаблон делегата, обравши відповідний зі списку в налаштуваннях завдання.

    search registry users by attributes 01

3.2. Налаштування делегата

У розділі Custom properties налаштуйте параметри пошуку. Секція Inputs дозволяє задати параметри для виконання пошуку.

3.2.1. Пошукові критерії

Ця секція описує можливі пошукові критерії, які можна використовувати для пошуку користувачів у реєстрі за атрибутами.

Важливо розуміти, що подані приклади наведені у вигляді JSON-об’єктів для зручності пояснення і можуть варіюватися залежно від специфіки API, через який ви робите запит.
Attributes Equals

Map атрибутів для точного пошуку.

Критерій Attributes Equals використовується для знаходження користувачів, атрибути яких точно збігаються зі вказаними значеннями.

Приклад JSON
{
  "Attributes Equals": {
    "department": "HR",
    "role": "manager"
  }
}

У цьому прикладі система знайде користувачів, у яких атрибут department точно дорівнює "HR" і атрибут role точно дорівнює "manager".

Attributes Starts With

Map атрибутів для пошуку за початковими символами.

Критерій Attributes Starts With шукає користувачів, атрибути яких починаються з вказаних у запиті символів.

Приклад JSON
{
  "Attributes Starts With": {
    "lastName": "Iva"
  }
}

Тут пошук буде здійснюватися серед користувачів, прізвище яких починається з "Iva", наприклад, "Ivanenko", "Ivanov" тощо.

Attributes that are start for

Map, що містить атрибути, значення яких мають бути початком для значень вказаних атрибутів користувача.

Критерій Attributes that are start for перевертає логіку пошуку Attributes Starts With, шукаючи користувачів, значення атрибутів яких є початком для значення, заданого в запиті.

Приклад JSON
{
  "Attributes that are start for": {
    "projectCode": "Proj123"
  }
}

У цьому випадку будуть знайдені користувачі, атрибути яких містять значення, що є початком для "Proj123". Наприклад, якщо користувач має атрибут projectCode зі значенням "Proj", він відповідає критерію.

3.2.2. Приклад пошуку за критерієм Attributes Starts With

Розглянемо приклад використання пошукового критерію Attributes Starts With.

Цей приклад виконає пошук користувачів, атрибут hierarchy_code яких починається з "01".

  1. Inputs  Attributes Starts With.

    1. Local variable assignment  ON

    2. Assignment type: Map

    3. Map entries: Задайте пари ключ-значення для пошуку.

    4. Realm: Вкажіть реалм (OFFICER або CITIZEN), у якому потрібно здійснити пошук користувачів.

    5. Limit: Максимальна кількість користувачів для виведення. Якщо не задано або ≤ 0, буде повернуто весь список користувачів.

    6. Continue token: Токен, що вказує на початок сторінки. У відповіді кожного пошуку користувачів від цього розширення буде continueToken, який вказує на наступну сторінку.

  2. Outputs  Result variable.
    Вкажіть змінну процесу, до якої буде записано відповідь зі списком користувачів, наприклад, usersResponse.

Приклад формування map атрибутів для пошуку
{
  "hierarchy_code": "${initiator().attributes["hierarchy_code"].get(0)}",
  "realm": "OFFICER",
  "limit": 10
}

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

Приклад. Тіло відповіді. Об’єкт зі списком користувачів та додатковою інформацією про пагінацію
{
  "users": [
    {
      "id": "userId",
      "userName": "userName",
      "fullName": "Іванов Іван Іванович",
      "attributes": {
        "edrpou": "11111111",
        "drfo": "1010101010"
      }
    },
    {
      "id": "userId2",
      "userName": "userName2",
      "fullName": "Петров Петро Петрович",
      "attributes": {
        "edrpou": "22222222",
        "drfo": "2020202020"
      }
    }
  ],
  "pagination": {
    "continueToken": 42
  }
}

4. Приклад

Нижче наведено референтний приклад, який демонструє використання делегата Search registry users by attributes:

search registry users by attributes 02
Зображення 1. Приклад. Референтний процес. Отримання списку користувачів реалму
search registry users by attributes 03
Зображення 2. Приклад. Референтний процес. Отримання списку користувачів реалму. Attributes Starts With
Де можна знайти приклад референтного бізнес-процесу?

Адміністратор Платформи може розгорнути для вас демо-реєстр — еталонний реєстр, що містить референтні та інші приклади файлів для створення цифрового регламенту. Він містить різноманітні елементи для розробки моделі даних, бізнес-процесів, UI-форм, аналітичної звітності, витягів, сповіщень, зовнішніх інтеграцій та багато іншого.

Еталонний регламент з прикладами для України зберігається в репозиторії ua-registry-demo-regulation.

Детальну інструкцію щодо розгортання демо-реєстру та отримання референтних прикладів моделювання ви знайдете на сторінці Розгортання демо-реєстру із референтними прикладами.

Приклад BPMN-схеми процесу буде доступний у регламенті демо-реєстру за пошуком по ключовим словам — reference-officers-management. Назви форм ви можете знайти всередині відповідних користувацьких задач бізнес-процесу у полі Form key.

5. Пов’язані сторінки