Конектор до фабрики даних (Connect to data factory)

🌐 Цей документ доступний українською та англійською мовами. Використовуйте перемикач у правому верхньому куті, щоб змінити версію.

1. Загальний огляд

Розширення Connect to data factory — загальний делегат для інтеграції бізнес-процесів із Фабрикою даних, який налаштовується за допомогою розробленого однойменного шаблону Connect to data factory (dataFactoryConnectorDelegate.json).

Завдяки цьому делегату можна надіслати будь-який запит до будь-якого АРІ-ендпоінту для отримання будь-яких даних. Тобто можна використати для запита будь-яку точку інтеграції (ендпоінт), розроблену на рівні Фабрики даних, яка відображена у REST API реєстру, тобто у Swagger UI.

Один цей загальний делегат здатен замінити усі інші делегати конкретного призначення.
Делегат підтримує взаємодію із HTTP-методами, а саме:

  • POST — для створення сутності/ресурсу. Відповідає БД-операції CREATE.

  • GET  — для пошуку або читання даних. Відповідає БД-операції READ.

  • PUT  — для оновлення сутності. Відповідає БД-операції UPDATE.

  • DELETE — для видалення сутності. Відповідає БД-операції DELETE).

  • PATCH  — для часткового оновлення (модифікації) сутності. Відповідає БД-операції UPDATE.

whats new 1 6 15

Перед налаштуванням шаблону в Сamunda Modeler переконайтеся, що папка із застосунком resources → element-templates містить файл dataFactoryConnectorDelegate.json.
Ця інструкція розглядає випадки взаємодії делегата з різними типами ендпоінтів на прикладі сутності ownership (право власності).

2. Налаштування взаємодії з POST-ендпоінтом

HTTP-метод POST використовується для створення сутності/ресурсу в базі даних реєстру.

Для налаштування шаблону делегата в Camunda Modeler, необхідно виконати наступні кроки:

  1. Створіть Service Task.

  2. На панелі налаштувань справа натисніть кнопку Open Catalog, оберіть відповідний шаблон Connect to data factory зі списку та натисніть Apply для підтвердження.

    connect to data factory delegate 1

  3. Сконфігуруйте обраний шаблон:

    • У полі Name вкажіть назву задачі. Наприклад, Створити сутність (POST).

    • Розгорніть блок Method у секції Custom Fields та оберіть з випадного списку HTTP-метод POST для взаємодії з Фабрикою даних.

      connect to data factory delegate 2

    • Розгорніть блок Path та вкажіть шлях до ресурсу у Фабриці даних, тобто назву ендпоінту, до якого необхідно звернутися:

      • Активуйте позначку Local Variable Assignment → ON. Це дозволить створити локальну змінну для ендпоінту.

      • У полі Variable Assignment Type оберіть з випадного списку тип призначення змінної — String or Expression.

      • У полі Variable Assignment Value вкажіть ендпоінт — /ownership.

        Назву ендпоінту необхідно вказувати через косу риску (/) як префікс.

      connect to data factory delegate 3

    • Метод POST не вимагає додаткових request-параметрів, окрім тіла запита, а отже блок Request parameters залиште порожнім.

      connect to data factory delegate 4

    • Розгорніть блок Payload та вкажіть вхідні параметри, тобто тіло запита:

      • Активуйте позначку Local Variable Assignment → ON. Це дозволить створити локальну змінну для тіла запита.

      • У полі Variable Assignment Type оберіть з випадного списку тип призначення змінної — String or Expression.

      • У полі Variable Assignment Value введіть тіло запита — JSON-структуру із параметрами, які необхідно записати до БД. Наприклад, ${payload}.

        У нашому прикладі ми передаємо змінну ${payload}, до якої були збережені дані в одній із попередніх задач бізнес-процесу.

        Приклад 1. Схема тіла запита згідно з REST API реєстру
        {
  "ownershipId": "b45b90c0-c53d-4fd3-aa82-02e8e7392345",
  "code": "string",
  "name": "string"
}

      connect to data factory delegate 5

    • Розгорніть блок X-Access-Token та вкажіть введіть токен доступу до ресурсу:

      • Активуйте позначку Local Variable Assignment → ON. Це дозволить створити локальну змінну для токена доступу.

      • У полі Variable Assignment Type оберіть з випадного списку тип призначення змінної — String or Expression.

      • У полі Variable Assignment Value введіть токен доступу. Наприклад, ${completer('taskId').accessToken}.

        Токен доступу береться з АБО ініціатора (наприклад, $initiator().accessToken}), АБО виконавця останньої користувацької задачі (наприклад, ${completer('taskDefinitionId').accessToken}).

      connect to data factory delegate 6

    • Розгорніть блок X-Digital-Signature source та вкажіть джерело для Ceph-документа, де зберігається підпис користувача (КЕП), накладений на дані UI-форми при внесенні:

      • Активуйте позначку Local Variable Assignment → ON. Це дозволить створити локальну змінну для КЕП.

      • У полі Variable Assignment Type оберіть з випадного списку тип призначення змінної — String or Expression.

      • У полі Variable Assignment Value вкажіть підпис користувача (КЕП). Наприклад, ${sign_submission('taskId').signatureDocumentId}.

        У нашому прикладі ми передаємо КЕП із користувацької форми, де його застосовано, через функцію sign_submission() (детальніше про використання JUEL-функцій у бізнес-процесах — за посиланням.)

      connect to data factory delegate 7

    • Розгорніть блок X-Digital-Signature-Derived source та вкажіть джерело для Ceph-документа, де зберігається системний підпис, автоматично накладений на тіло запита:

      • Активуйте позначку Local Variable Assignment → ON. Це дозволить створити локальну змінну для системного підпису.

      • У полі Variable Assignment Type оберіть з випадного списку тип призначення змінної — String or Expression.

      • У полі Variable Assignment Value передайте системний підпис. Наприклад, `${createPersonPayloadDerivedKey}.

        У нашому прикладі ми передаємо змінну ${createPersonPayloadDerivedKey}, до якої було збережено системний підпис в одній із попередніх задач бізнес-процесу.

      connect to data factory delegate 8

    • Розгорніть блок Result variable та вкажіть назву змінної процесу, до якої необхідно записати результат (за замовчуванням — response):

      • Активуйте позначку Local Variable Assignment → ON.

      • У полі Variable Assignment Type оберіть з випадного списку тип призначення змінної — String or Expression.

      • У полі Variable Assignment Value введіть назву результівної змінної (за замовчуванням — response).

        Сервіс не повертає тіла у відповідь на POST-запит. В результаті повертається лише код відповіді та його опис.

        Приклад 2. Код відповіді та його опис згідно з REST API реєстру
        201
OK, ресурс успішно створено

    connect to data factory delegate 9

3. Налаштування взаємодії з GET-ендпоінтом

HTTP-метод GET використовується для отримання даних сутності (SELECT за id із таблиці в БД) або пошуку даних за певними критеріями (SELECT із представлення (view)) в базі даних реєстру. Використовується для отримання об’єктів. Не змінює стан ресурсу.

КЕП і системний підпис не використовуються при GET-запиті.
Отримання даних сутності за id

Цей випадок описує приклад отримання ресурсу за його ID із певної таблиці в базі даних.

Для налаштування шаблону делегата в Camunda Modeler, необхідно виконати наступні кроки:

  1. Створіть Service Task.

  2. На панелі налаштувань справа натисніть кнопку Open Catalog, оберіть відповідний шаблон Connect to data factory зі списку та натисніть Apply для підтвердження.

    connect to data factory delegate 1

  3. Сконфігуруйте обраний шаблон:

    • У полі Name вкажіть назву задачі. Наприклад, Отримати сутніть за id (GET).

    • Розгорніть блок Method у секції Custom Fields та оберіть з випадного списку HTTP-метод GET для взаємодії з Фабрикою даних.

      connect to data factory delegate 10

    • Розгорніть блок Path та вкажіть шлях до ресурсу у Фабриці даних, тобто назву ендпоінту, до якого необхідно звернутися:

      • Активуйте позначку Local Variable Assignment → ON. Це дозволить створити локальну змінну для ендпоінту.

      • У полі Variable Assignment Type оберіть з випадного списку тип призначення змінної — String or Expression.

      • У полі Variable Assignment Value вкажіть ендпоінт. Наприклад, /ownership/${response.value.responseBody.prop('id).value()}.

        Назву ендпоінту необхідно вказувати через косу риску (/) як префікс.

        Обов’язково необхідно передати ідентифікатор сутності. ID можна передати декількома способами. Наприклад:

        • через змінну як ${response.value.responseBody.prop('id).value()};

        • через змінну як /${id};

        • через функцію submission() як ${submission('taskId').formData.prop('id').value()}

        • через константне значення UUID напряму — /b45b90c0-c53d-4fd3-aa82-02e8e7392345.

        connect to data factory delegate 11

    • Цей випадок не вимагає додаткових request-параметрів, окрім параметрів шляху (path params), а отже блоки Request parameters та Payload залиште порожніми.

    • Розгорніть блок X-Access-Token та вкажіть введіть токен доступу до ресурсу:

      • Активуйте позначку Local Variable Assignment → ON. Це дозволить створити локальну змінну для токена доступу.

      • У полі Variable Assignment Type оберіть з випадного списку тип призначення змінної — String or Expression.

      • У полі Variable Assignment Value введіть токен доступу. Наприклад, ${completer('taskId').accessToken}.

        Токен доступу береться з АБО ініціатора (наприклад, $initiator().accessToken}), АБО виконавця останньої користувацької задачі (наприклад, ${completer('taskDefinitionId').accessToken}).

        connect to data factory delegate 12

    • Розгорніть блок Result variable вкажіть назву змінної процесу, до якої необхідно записати результат (за замовчуванням — response):

      • Активуйте позначку Local Variable Assignment → ON.

      • У полі Variable Assignment Type оберіть з випадного списку тип призначення змінної — String or Expression.

      • У полі Variable Assignment Value введіть назву результівної змінної (за замовчуванням — response).

        У відповідь на GET-запит сервіс повертає ресурс за його ID.

        Приклад 3. Приклад тіла відповіді згідно з REST API реєстру
        {
  "ownershipId": "b45b90c0-c53d-4fd3-aa82-02e8e7392345",
  "code": "string",
  "name": "string"
}

        connect to data factory delegate 13

Пошук даних за критеріями

Цей випадок описує приклад отримання списку ресурсів через запит до ендпоінту, що згенерований на базі відповідного представлення (Search Condition) у Фабриці даних.

Для налаштування шаблону делегата в Camunda Modeler, необхідно виконати наступні кроки:

  1. Створіть Service Task.

  2. На панелі налаштувань справа натисніть кнопку Open Catalog, оберіть відповідний шаблон Connect to data factory зі списку та натисніть Apply для підтвердження.

    connect to data factory delegate 1

  3. Сконфігуруйте обраний шаблон:

    • У полі Name вкажіть назву задачі. Наприклад, Пошук даних за критеріями (GET).

    • Розгорніть блок Method у секції Custom Fields та оберіть з випадного списку HTTP-метод GET для взаємодії з Фабрикою даних.

      connect to data factory delegate 14

    • Розгорніть блок Path та вкажіть шлях до ресурсу у Фабриці даних, тобто назву ендпоінту, до якого необхідно звернутися:

      • Активуйте позначку Local Variable Assignment → ON. Це дозволить створити локальну змінну для ендпоінту.

      • У полі Variable Assignment Type оберіть з випадного списку тип призначення змінної — String or Expression.

      • У полі Variable Assignment Value вкажіть ресурс. Наприклад, /staff-equal-constant-code.

        • Назва ресурсу відповідає назві ендпоінту для Search Condition у Фабриці даних.

        • Назву ресурсу необхідно вказувати через косу риску (/) як префікс.

        connect to data factory delegate 15

    • Цей випадок вимагає налаштування додаткових параметрів запита — query-параметрів. Розгорніть блок Request parameters та вкажіть query-параметри як пари ключ-значення (Map).

      • Активуйте позначку Local Variable Assignment → ON. Це дозволить створити локальну змінну ендпоінту для Search Condition.

      • У полі Variable Assignment Type оберіть з випадного списку тип призначення змінної — Map.

      • У полі Variable Assignment Value введіть ключ пошуку — constantCode та його значення — ${submission('formId').formData.prop('staffStatusCode').value()}.

        У нашому випадку значення ключа пошуку constantCode передається через функцію submission() (детальніше про використання JUEL-функцій у бізнес-процесах — за посиланням.). Інші параметри є опціональними.

        Приклад 4. Приклад query-параметрів запита у форматі JSON згідно з REST API реєстру
        {
"offset": 0,
"constantCode": "string",
"limit": 0
}

        connect to data factory delegate 16

    • Розгорніть блок X-Access-Token та вкажіть введіть токен доступу до ресурсу:

      • Активуйте позначку Local Variable Assignment → ON. Це дозволить створити локальну змінну для токена доступу.

      • У полі Variable Assignment Type оберіть з випадного списку тип призначення змінної — String or Expression.

      • У полі Variable Assignment Value введіть токен доступу. Наприклад, ${completer('taskId').accessToken}.

        Токен доступу береться з АБО ініціатора (наприклад, $initiator().accessToken}), АБО виконавця останньої користувацької задачі (наприклад, ${completer('taskDefinitionId').accessToken}).

        connect to data factory delegate 17

    • Розгорніть блок Result variable вкажіть назву змінної процесу, до якої необхідно записати результат (за замовчуванням — response):

      • Активуйте позначку Local Variable Assignment → ON.

      • У полі Variable Assignment Type оберіть з випадного списку тип призначення змінної — String or Expression.

      • У полі Variable Assignment Value введіть назву результівної змінної (за замовчуванням — response).

        У відповідь на GET-запит сервіс повертає масив об’єктів/ресурсів за критеріями пошуку.

        Приклад 5. Приклад тіла відповіді від сервісу згідно з REST API реєстру
        [
  {
    "staffStatusId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "constantCode": "string",
    "name": "string"
  }
]

        connect to data factory delegate 18

4. Налаштування взаємодії з PUT-ендпоінтом

HTTP-метод PUT використовується для оновлення сутності/ресурсу в базі даних реєстру. Використовується для зміни наявного ресурсу за вказаним ID.

Принцип налаштування делегата для оновлення сутності є ідентичним до Налаштування взаємодії з POST-ендпоінтом за декількома винятками:

  • Розгорніть блок Method у секції Custom Fields та оберіть з випадного списку HTTP-метод PUT для взаємодії з Фабрикою даних.

    connect to data factory delegate 19

  • У блоці Path вкажіть ендпоінт /ownership/${response.value.responseBody.prop('id).value()} як локальну зміну із зазначенням ідентифікатора ресурсу, який необхідно оновити.

    connect to data factory delegate 20

    У нашому випадку ми передаємо значення id як змінну ${response.value.responseBody.prop('id).value()} (детальніше про опції передачі id ви можете переглянути у розділі Налаштування взаємодії з GET-ендпоінтом).

  • У блоці Result variable до результівної змінної зберігається такий код відповіді:

Приклад 6. Код відповіді та його опис згідно з REST API реєстру
204 OK

5. Налаштування взаємодії з DELETE-ендпоінтом

HTTP-метод DELETE використовується для видалення сутності/ресурсу в базі даних реєстру. Використовується для видалення ресурсу за вказаним ID.

Принцип налаштування делегата для видалення сутності є ідентичним до Налаштування взаємодії з PUT-ендпоінтом за двома винятками:

  • У блоці Method вкажіть метод DELETE як локальну змінну.

    connect to data factory delegate 21

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

    connect to data factory delegate 21 1

6. Налаштування взаємодії з PATCH-ендпоінтом

HTTP-метод PATCH використовується для часткового оновлення сутності/ресурсу в базі даних реєстру. Використовується для модифікації конкретних параметрів ресурсу за вказаним ID.

Принцип налаштування делегата для часткового оновлення сутності є ідентичним до Налаштування взаємодії з PUT-ендпоінтом за одним винятком:

  • Розгорніть блок Method у секції Custom Fields та оберіть з випадного списку HTTP-метод PATCH для взаємодії з Фабрикою даних.

    connect to data factory delegate 22