JUEL functions in business processes

🌐 This document is available in both English and Ukrainian. Use the language toggle in the top right corner to switch between versions.

1. General overview

In Camunda, you can use scripts in various locations in the business process. For example, when working with the Script Task. Camunda Engine supports scripting languages such as JavaScript, Groovy, JUEL, etc.

In the context of the Registry Platform, scripting support is implemented using Groovy and JUEL (Java Unified Expression Language) — a unified scripting language for Java expressions - using specially developed JUEL functions.

Use the platform JUEL functions to simplify business process modeling. Currently, the following functions and their auto-completion are implemented in the visual code editor:

You can find more information about using the code editor on the following page: Editing business process scripts in a visual code editor.

2. Initiator function()

The initiator() function is intended to obtain and further use the initiator (initiator) in the process. Returns the UserDto class.

Always contains userName, token, and JwtClaimsDto (authorization data) for the first user task

UserDto — is a class that is a wrapper for user data (in this case - the initiator). Always contains userName, token, and JwtClaimsDto (authentication data) up to the user’s first task.

Methods of interaction

The function provides the following methods:

  • getUserName() — returns the username that can be used in the Assignee and Candidate Users fields of user tasks.

  • getAccessToken() — returns the user token that can be used in integration connectors to integrate on behalf of the user.

  • getFullName() — delegates the call to JwtClaimsDto and returns the Keycloak attribute fullName of the user

    This functionality is specific to the Ukrainian implementation and may not apply or function as described in other contexts or regions. Please consult the local guidelines or documentation if you are implementing this outside Ukraine.

    • getDrfo() — delegates the call to JwtClaimsDto and returns the Keycloak attribute drfo (State Register of Individuals – Taxpayers) of the user.

    • getEdrpou() — delegates the call to JwtClaimsDto and returns the Keycloak attribute edrpou (Unified state register of enterprises and organizations of Ukraine) of the user.

The initiator token, along with all Keycloak attributes, will only be available up to the user’s first user task (User Task) in the business process

3. Completer function()

The completer(<task_id>) function allows retrieving the performer of a user task for further use in the process. Returns the UserDto class.

UserDto —  is a class that is a wrapper for user data (in this case — the initiator). Always contains userName, token, and JwtClaimsDto (authentication data).

Methods of interaction

The function provides the following methods:

  • getUserName() — returns the username that can be used in the Assignee and Candidate Users fields of user tasks.

  • getAccessToken() — -- returns the user token that can be used in integration connectors to integrate on behalf of the user.

  • getFullName() — Delegates the call to JwtClaimsDto and returns the Keycloak attribute fullName of the user

    This functionality is specific to the Ukrainian implementation and may not apply or function as described in other contexts or regions. Please consult the local guidelines or documentation if you are implementing this outside Ukraine.

    • getDrfo() — delegates the call to JwtClaimsDto and returns the Keycloak attribute drfo (State Register of Individuals – Taxpayers) of the user.

    • getEdrpou() — delegates the call to JwtClaimsDto and returns the Keycloak attribute edrpou (Unified state register of enterprises and organizations of Ukraine) of the user.

The completer(<task_id>) function is available for use after a user task has been successfully completed.

4. Submission function()

The submission(<activity_id|event_id>) function allows retrieving user task form data and returns the UserFormDataDto class.

UserFormDataDto — a class that is a wrapper for user task form data.
The submission(<activity_id|event_id>) function is available for use after a user task or start form has been successfully completed.

5. Sign_submission function()

The sign_submission(<activity_id|event_id>) function is used to obtain the signature and user task form data.
Returns the SignUserFormDataDto class.

SignUserFormDataDto — a class that is a wrapper for user task form data, signature, and the CEPH document key where the signature is stored.
The `sign_submission(<activity_id|event_id>)`function is available for use after a user task requiring user signature validation has been successfully completed or a start form.

6. System_user function()

The system_user() function required to obtain a system user from Keycloak.
Returns the `UserDto`class.

UserDto — a class that is a wrapper for user data (in this case - the initiator). Always contains userName, token, and JwtClaimsDto.

Methods of interaction

The function provides the following methods:

  • getUserName() — returns the username that can be used in the Assignee and Candidate Users fields of user tasks.

  • getAccessToken() — -- returns the user token that can be used in integration connectors to integrate on behalf of the user.

  • getFullName() — Delegates the call to JwtClaimsDto and returns the Keycloak attribute fullName of the user

    This functionality is specific to the Ukrainian implementation and may not apply or function as described in other contexts or regions. Please consult the local guidelines or documentation if you are implementing this outside Ukraine.

    • getDrfo() — delegates the call to JwtClaimsDto and returns the Keycloak attribute drfo (State Register of Individuals – Taxpayers) of the user.

    • getEdrpou() — delegates the call to JwtClaimsDto and returns the Keycloak attribute edrpou (Unified state register of enterprises and organizations of Ukraine) of the user.

7. Working with digital documents

7.1. Load_digital_document function()

JUEL function load_digital_document(String documentId): byte[] is designed to load digital documents. This function uses the document identifier (documentId), which is passed as an input parameter to obtain the corresponding document through the internal API of the digital document service.

Internal API of the digital document service.
GET /internal-api/documents/{processInstanceId}/{id} (binary response)

The function returns the document in byte format — byte[], which allows working with document data at a low level. This function can be useful for developers who need to work with digital documents using Groovy scripting.

The usage of the load_digital_document() function is detailed in the reference example on the following page: Uploading and editing a file.

7.2. Get_digital_document_metadata function()

JUEL function get_digital_document_metadata(String documentId): DocumentMetadata is used to obtain document metadata stored in the digital document service.

Internal API of the digital document service.
GET /internal-api/documents/{processInstanceId}/{id}/metadata (DocumentMetadata)

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

This function takes the document identifier (documentId) as input and returns an object of type DocumentMetadata, which includes the following information:

  • id: the identifier of the document.

  • name: the name of the document.

  • type: the type of the document.

  • checksum: the document checksum. Used for checking the integrity of the document after it has been transmitted or saved.

  • size: the size of the document.

This function can be useful when you need to obtain document metadata within your business process. It allows you to work with documents in the digital document service without making direct requests to the API of this service. Instead, you can use this JUEL function directly in the Groovy editor.

The usage of the get_digital_document_metadata() function is detailed in the reference example on the following page: Uploading and editing a file.

7.3. Save_digital_document function()

JUEL function save_digital_document(byte[] content, String targetFileName): DocumentMetadata is used to save a document in the digital document service."

This function takes two arguments:

  • content: the byte array that represents the contents of the document that needs to be saved.

  • targetFileName: the name of the file under which the document will be saved.

Internal API of the digital document service.
POST /internal-api/documents/{processInstanceId} (multipart file + filename) : DocumentMetadata

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

After execution, this function returns an object of type DocumentMetadata, which contains the metadata of the newly saved document. These metadata include:

  • id: the identifier of the new document.

  • name: the name of the new document (will be the same as the targetFileName that was passed).

  • type: the type of the new document.

  • checksum: the checksum of the new document, which is used to verify its integrity.

  • size: the size of the new document in bytes.

This function is very useful when you need to save a document within your business processes. Instead of making direct requests to the API of the digital document service, you can use this JUEL function directly in the Groovy editor.

The usage of the save_digital_document() function is detailed in the reference example on the following page: Uploading and editing a file.

7.4. Save_digital_document_from_url function()

save_digital_document_from_url() function allows you to obtain digital files/documents from a remote address from public APIs, i.e. those that do not require authentication. It can be used to simplify business process modeling in scripts.

The function can take 2 input parameters:

  • The URL of the digital document

  • The name of the file

    It is possible to obtain only one document per request from an external source.

    Both parameters are of type (String), so the modeler can actually pass any argument to the function:

    Example 1. Template of function
    save_digital_document_from_url(String remoteFileUrl, String targetFileName)

You can learn more about how the function works and its usage in business processes on the following page: Downloading digital documents at an external link.