Створення декількох сутностей в рамках однієї транзакції: Create nested entities in data factory

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

Інтеграційне розширення Create nested entities in data factory дозволяє налаштовувати завдання для створення декількох сутностей у рамках однієї транзакції під час виконання бізнес-процесу. Це розширення допомагає автоматизувати процеси збереження складних даних до БД, забезпечуючи належне оброблення запитів та передачу даних між процесами. Розширення додає різні властивості до завдання типу Service Task.

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

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

Create nested entities in data factory

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

${dataFactoryConnectorNestedCreateDelegate}

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

dataFactoryConnectorNestedCreateDelegate.json

Розширення Create nested entities in data factory використовується, коли необхідно створити декілька взаємопов’язаних (вкладених) записів у базі даних у рамках однієї транзакції.

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

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

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

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

3. Налаштування

Делегат Create nested entities in data factory призначений для використання у завданнях типу Service Task бізнес-процесу. Він дозволяє налаштувати створення декількох записів з передачею вхідних та вихідних даних у рамках однієї транзакції.

3.1. Налаштування завдання

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

  2. Назвіть завдання, наприклад, Зберегти дані до Фабрики даних.

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

    create nested entities 1

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

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

Resource

У полі Resource вкажіть назву ендпоінту / таблицю, до якої необхідно звернутися. Наприклад, person-profile.

На рівні API, ендпоінт виглядає наступним чином: /nested/<resource name>, де <resource name> — назва ресурсу. Тобто у полі Resource необхідно вказати значення, яке визначається після останньої косої риски (/).
Payload

У полі Payload введіть тіло запита — JSON-об’єкт із вкладеною структурою декількох сутностей, яку необхідно зберегти до Фабрики даних. Наприклад, ${createComplexPayload}.

Необхідно попередньо побудувати цей JSON-об’єкт, тобто payload, в рамках задачі скриптування.

Приклад. Groovy-скрипт, що формує комплексний JSON-об’єкт для подальшого запису до БД
def personProfileId = createPersonProfileResponse.responseBody.prop('id').value()

        def personEduProfile = ['personProfileId':personProfileId]

        def formData = submission('signPersonProfileActivity').formData

        def orders = [:]
        orders['ordersType'] = formData.prop('order_type').value()
        orders['ordersNumber'] = formData.prop('order_number').value()
        orders['ordersDate'] = formData.prop('order_date').value()
        orders['personProfileId'] = personProfileId

        def cephData = ['personEduProfile':personEduProfile,'orders':orders]

        set_transient_variable('createComplexPayload', S(cephData, 'application/json'))

Пояснення роботи скрипту, який формує об’єкт createComplexPayload:

Цей скрипт виконує ряд дій для створення об’єкта createComplexPayload, який містить дані про профіль особи та пов’язані з ним освітні профілі та накази. Ці дані потім зберігаються як транзитна змінна для подальшого використання у бізнес-процесі.

  1. Отримання ID профілю особи:

    def personProfileId = createPersonProfileResponse.responseBody.prop('id').value()

    Цей рядок отримує значення id з відповіді на створення профілю особи createPersonProfileResponse та зберігає його у змінній personProfileId.

  2. Створення об’єкта personEduProfile:

    def personEduProfile = ['personProfileId':personProfileId]

    Тут створюється об’єкт personEduProfile, який містить personProfileId.

  3. Отримання даних з форми:

    def formData = submission('signPersonProfileActivity').formData

    Цей рядок отримує дані з форми, яка була заповнена користувачем у завданні signPersonProfileActivity, та зберігає їх у змінній formData.

  4. Формування об’єкта orders:

    def orders = [:]
orders['ordersType'] = formData.prop('order_type').value()
orders['ordersNumber'] = formData.prop('order_number').value()
orders['ordersDate'] = formData.prop('order_date').value()
orders['personProfileId'] = personProfileId

    Тут створюється порожній об’єкт orders у вигляді мапи (словника). Далі у цю мапу додаються наступні поля:

    • ordersType з значенням поля order_type з форми.

    • ordersNumber з значенням поля order_number з форми.

    • ordersDate з значенням поля order_date з форми.

    • personProfileId з раніше отриманим значенням personProfileId.

  5. Формування об’єкта cephData:

    def cephData = ['personEduProfile':personEduProfile,'orders':orders]

    Тут створюється об’єкт cephData, який містить два вкладені об’єкти: personEduProfile та orders.

  6. Створення транзитної змінної createComplexPayload:

    set_transient_variable('createComplexPayload', S(cephData, 'application/json'))

    Цей рядок перетворює об’єкт cephData у формат JSON та зберігає його як транзитну змінну createComplexPayload.

Дані, що передаються для створення записів, повинні мати відповідний формат:

Приклад. Тіло запита. Сформований JSON-об’єкт, збережений до змінної 'createComplexPayload'
{
  "personEduProfile": {
    "personProfileId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  },
  "orders": {
    "ordersType": "string",
    "ordersNumber": "string",
    "ordersDate": "2022-02-16T13:33:30.660Z",
    "personProfileId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  }
}
HTTP-код: 
200 OK
Тіло відповіді: 
{
   "id":"d1394f5d-5274-4831-90ac-0dfdb6d7bd35"
}

Для окремого типу запита використовують окремий делегат. Тобто в загальному випадку є REST-контролер, який підтримує певні типи запитів (методи): POST, GET, PUT, PATCH та DELETE. Для кожного методу — свій делегат.

Для ресурсу /nested/<resource name> та делегата $dataFactoryConnectorNestedCreateDelegate використовується ЛИШЕ метод PUT.

І хоча метод PUT зазвичай використовується для оновлення записів, та у нашому випадку PUT може як створити сутність, так і оновити її, в залежності від того, які параметри ми передаємо у запиті:

  • Якщо необхідно створити сутність, то ми НЕ передаємо параметр <table_primary_key>_id у тілі запита. Наприклад, orders_id.

  • Якщо необхідно оновити сутність, то ми включаємо параметр <table_primary_key>_id у тіло запита. Наприклад, orders_id.
X-Access-Token

У полі X-Access-Token вкажіть токен доступу користувача, під яким виконується операція. Цей токен забезпечує повноваження виконавця задачі щодо доступу до даних.

  • Наприклад, вкажіть токен ініціатора процесу через JUEL-функцію initiator(), використавши метод accessToken:

    ${initiator().accessToken}

  • Альтернативно, ви можете вказати токен виконавця останнього користувацького завдання. Для цього ви можете використати JUEL-функцію completer(), передавши ID попередньої задачі та використавши метод accessToken. Наприклад:

    ${completer('UserTask_SignDataBuildInfo').accessToken}

    • completer() — назва JUEL-функції.

    • 'UserTask_SignDataBuildInfo' — ID попередньої задачі користувача.

    • accessToken — метод, який передає JWT-токен користувача.

X-Digital-Signature source

У полі X-Digital-Signature source вкажіть джерело цифрового підпису. Це поле вказує на Ceph-документ із цифровим підписом даних КЕП на стороні користувача (див. детальніше про підпис КЕП у делегатах Підписання даних КЕП надавача послуг: Officer Sign Task та Підписання даних КЕП отримувача послуг: Citizen Sign Task). Функція sign_submission() та метод signatureDocumentId дозволяють отримати підписані дані з UI-форми та передати ID Ceph-документа. Наприклад:

${sign_submission('UserTask_SignDataBuildInfo').signatureDocumentId}

  • sign_submission — назва JUEL-функції.

  • 'UserTask_SignDataBuildInfo' — ID завдання користувача, із даними, на які накладено КЕП.

  • signatureDocumentId — метод, який дозволяє отримати ID Ceph-документа, в якому зберігаються підписані КЕП дані.

X-Digital-Signature-Derived source

У полі X-Digital-Signature-Derived source вкажіть джерело системного цифрового підпису (цифрової печатки). Це поле вказує на Ceph-документ із системним цифровим підписом (цифровою печаткою), накладеним на дані. Наприклад, ${system_signature_key}.

Значення ключа/ідентифікатора системного підпису можна отримати після підпису даних за допомогою делегата Підписання даних системним ключем: System signature by DSO service. Результат виконання операції підписання даних системним ключем буде збережено до вказаної змінної, наприклад, system_signature_key. Надалі ви зможете використати змінну в іншому місці процесу, зокрема під час збереження даних до БД або для генерування витягу тощо.
Result variable

У полі Result variable задайте ім’я для змінної, в якій буде зберігатися відповідь від операції створення сутності, наприклад, response.

4. Приклад

Ось приклад, який показує, як відповідний делегат використовується у бізнес-процесі:

create nested entities 2
Зображення 1. Приклад. Налаштування делегата Create nested entities in data factory
Де можна знайти приклад бізнес-процесу?

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

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

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

Create nested entities in data factory — делегат, який використовується у деяких бізнес-процесах, що потребують створення декількох взаємопов’язаних записів у БД.

Ви можете використати один із прикладів процесів за пошуком по ключовим словам — feature-nested-entity-test-process.

У Кабінеті користувача бізнес-процес буде доступний у розділі Доступні послуги.

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