JUEL-функції у бізнес-процесах

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

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

У Camunda ви можете використовувати скрипти в різних місцях бізнес-процесу. Наприклад, при роботі зі Script Task. Camunda Engine підтримує скриптування мовами JavaScript, Groovy або JUEL тощо.

У розрізі Платформи реєстрів реалізовано підтримку скриптування за допомогою Groovy та JUEL (Java Unified Expression Language) — уніфікованої скриптової мови виразів Java — з використанням спеціальних розроблених JUEL-функцій.

Використовуйте платформні JUEL-функції для спрощення моделювання бізнес-процесів. Наразі імплементовано такі функції та їх автодоповнення у візуальному редакторі коду:

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

2. Функція initiator()

Функція initiator() призначена для отримання та подальшого використання ініціатора (initiator) в процесі.
Повертає клас UserDto.

UserDto — клас, що є обгорткою даних користувача (тут — ініціатора). Завжди містить у собі userName, токен і JwtClaimsDto (дані для авторизації) до першої задачі користувача.

Методи взаємодії

Функція надає наступні методи:

  • getUserName() — повертає ім’я користувача, що можна використовувати в полях Assignee та Candidate Users задач користувача.

  • getAccessToken() — повертає токен користувача, що можна використовувати в інтеграційних конекторах для інтеграції від імені користувача.

  • getDrfo() — делегує виклик на JwtClaimsDto та повертає Keycloak-атрибут drfo користувача.

  • getEdrpou() — делегує виклик на JwtClaimsDto та повертає Keycloak-атрибут edrpou користувача.

  • getFullName() — делегує виклик на JwtClaimsDto та повертає Keycloak-атрибут fullName користувача.

Токен ініціатора, а разом з ним і всі атрибути Keycloak, будуть доступні тільки до першої користувацької задачі (User Task) у бізнес-процесі.

3. Функція completer()

Функція completer(<task_id>) дозволяє отримати виконавця користувацької задачі для подальшого використання у процесі.
Повертає клас UserDto.

UserDto — клас, що є обгорткою даних користувача (тут — ініціатора). Завжди містить у собі userName, токен і JwtClaimsDto (дані для авторизації).

Методи взаємодії

Функція надає наступні методи:

  • getUserName() — повертає ім’я користувача, що можна використовувати в полях Assignee та Candidate Users задач користувача.

  • getAccessToken() — повертає токен користувача, що можна використовувати в інтеграційних конекторах для інтеграції від імені користувача.

  • getDrfo() — делегує виклик на JwtClaimsDto та повертає Keycloak-атрибут drfo користувача.

  • getEdrpou() — делегує виклик на JwtClaimsDto та повертає Keycloak-атрибут edrpou користувача.

  • getFullName() — делегує виклик на JwtClaimsDto та повертає Keycloak-атрибут fullName користувача.

Функція completer(<task_id>) доступна для використання після успішного завершення користувацької задачі.

4. Функція submission()

Функція submission(<activity_id|event_id>) дозволяє отримати дані форми користувацької задачі та повертає клас UserFormDataDto.

UserFormDataDto — клас, що є обгорткою даних форми користувача.
Функція submission(<activity_id|event_id>) доступна для використання після успішного завершення користувацької задачі або стартової форми.

5. Функція sign_submission()

Функція sign_submission(<activity_id|event_id>) використовується для отримання підпису та даних форми користувацьких задач.
Повертає клас SignUserFormDataDto.

SignUserFormDataDto — клас, що є обгорткою для даних форми користувача, підпису та ключа CEPH-документа, де зберігається підпис.
Функція sign_submission(<activity_id|event_id>) доступна для використання після успішного завершення задачі, що потребує валідації підписом користувача, або стартової форми.

6. Функція system_user()

Функція system_user() необхідна для отримання системного користувача з Keyclock.
Повертає клас UserDto.

UserDto — клас, що є обгорткою даних користувача (тут — ініціатора). Завжди містить у собі userName, токен і JwtClaimsDto.

Методи взаємодії

Функція надає наступні методи:

  • getUserName() — повертає ім’я користувача, що можна використовувати в полях Assignee та Candidate Users задач користувача.

  • getAccessToken() — повертає токен користувача, що можна використовувати в інтеграційних конекторах для інтеграції від імені користувача.

  • getDrfo() — делегує виклик на JwtClaimsDto та повертає Keycloak-атрибут drfo користувача.

  • getEdrpou() — делегує виклик на JwtClaimsDto та повертає Keycloak-атрибут edrpou користувача.

  • getFullName() — делегує виклик на JwtClaimsDto та повертає Keycloak-атрибут fullName користувача.

7. Функція get_trembita_auth_token()

Функція get_trembita_auth_token() дозволяє отримати токен авторизації для доступу до сервісів СЕВ ДЕІР "Трембіта", з якими попередньо налаштовано взаємодію. Така взаємодія конфігурується в інтерфейсі адміністративної панелі Control Plane (див. детальніше — Налаштування взаємодії з реєстрами через ШБО "Трембіта" у Control Plane).

Функція застосовується у скрипт-задачах (Script Task) бізнес-процесів і приймає один параметр (String) — назву системи/сервісу, до якої необхідно виконати запит. Наприклад:

Приклад 1. Використання get_trembita_auth_token() у скрипті
def registryAuthSecretValue = get_trembita_auth_token('trembita-registry-test')

  • trembita-registry-test — назва системи у СЕВ ДЕІР "Трембіта".

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

8. Робота з цифровими документами

8.1. Функція load_digital_document()

JUEL-функція load_digital_document(String documentId): byte[] призначена для завантаження цифрових документів. Ця функція використовує ідентифікатор документа (documentId), який передається як вхідний параметр для отримання відповідного документа через внутрішній API сервісу цифрових документів.

Службовий API сервісу цифрових документів
GET /internal-api/documents/{processInstanceId}/{id} (binary response)

Функція повертає документ у форматі байтів — byte[], що дозволяє працювати з даними документа на низькому рівні. Ця функція може бути корисна для розробників, яким потрібно працювати з цифровими документами, використовуючи скриптування Groovy.

Застосування функції load_digital_document() детально представлено у референтному прикладі на сторінці Завантаження файлу та його редагування.

8.2. Функція get_digital_document_metadata()

JUEL-функція get_digital_document_metadata(String documentId): DocumentMetadata використовується для отримання метаданих документа, які зберігаються в сервісі цифрових документів.

Службовий API сервісу цифрових документів
GET /internal-api/documents/{processInstanceId}/{id}/metadata (DocumentMetadata)

class DocumentMetadata {
  String id
  String name
  String type
  String checksum
  Long size
}

Ця функція приймає на вхід ідентифікатор документа (documentId) і повертає об’єкт типу DocumentMetadata, що містить наступну інформацію:

  • id: ідентифікатор документа.

  • name: ім’я документа.

  • type: тип документа.

  • checksum: контрольна сума документа. Використовується для перевірки цілісності документа після його передачі або збереження.

  • size: розмір документа.

Ця функція може бути корисною, коли вам потрібно отримати метадані документа в рамках вашого бізнес-процесу. Вона дозволяє вам працювати з документами в сервісі цифрових документів, не здійснюючи прямі запити до API цього сервісу. Замість цього, ви можете використовувати цю JUEL-функцію безпосередньо в Groovy-редакторі.

Застосування функції get_digital_document_metadata() детально представлено у референтному прикладі на сторінці Завантаження файлу та його редагування.

8.3. Функція save_digital_document()

JUEL-функція save_digital_document(byte[] content, String targetFileName): DocumentMetadata використовується для збереження документа в сервісі цифрових документів.

Ця функція приймає два аргументи:

  • content: це байтовий масив, що представляє вміст документа, який потрібно зберегти.

  • targetFileName: це ім’я файлу, під яким буде збережено документ.

Службовий API сервісу цифрових документів
POST /internal-api/documents/{processInstanceId} (multipart file + filename) : DocumentMetadata

class DocumentMetadata {
  String id
  String name
  String type
  String checksum
  Long size
}

Після виконання, ця функція повертає об’єкт типу DocumentMetadata, що містить метадані новозбереженого документа. Ці метадані включають:

  • id: ідентифікатор нового документа.

  • name: ім’я нового документа (це буде те саме ім’я, що було передано як targetFileName).

  • type: тип нового документа.

  • checksum: контрольна сума нового документа, що використовується для перевірки його цілісності.

  • size: розмір нового документа в байтах.

Ця функція дуже корисна, коли вам потрібно зберегти документ в рамках ваших бізнес-процесів. Замість того, щоб робити прямі запити до API сервісу цифрових документів, ви можете використовувати цю JUEL-функцію прямо в Groovy-редакторі.

Застосування функції save_digital_document() детально представлено у референтному прикладі на сторінці Завантаження файлу та його редагування.

8.4. Функція save_digital_document_from_url()

Функція save_digital_document_from_url() дозволяє отримувати цифрові файли/документи за віддаленою адресою від публічних API, тобто таких, що не потребують автентифікації. ЇЇ можна використовувати для спрощення моделювання бізнес-процесів у скриптах.

Функція може приймати 2 вхідні параметри:

  • URL цифрового документа

  • Назва файлу

    Можливо отримати лише один документ за один запит до зовнішнього джерела.

    Обидва параметри є рядком (String), тому моделювальник може передати функції фактично будь-який аргумент:

    Приклад 2. Шаблон функції
    save_digital_document_from_url(String remoteFileUrl, String targetFileName)

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