Operations and access to process data

Process data operations and access

---

API

interface ProcessApi {
    v1: {
        // Sends messages to the process; process variables can optionally be passed
        correlateMessage(messageName: string, processVariables?: { [key: string]: string });

        // Sets the list of groups that have access to the process instance in the cases list
        setAccessGroups(groupNames: string[]);

        // Starts a new process based on the process definition key; business key and process variables can optionally be passed. Returns the process instance identifier.
        startProcess(definitionKey: string, data?: StartProcessOptions): string;

        // Allows you to reference another process based on its instance identifier. Enables operations on that process, such as sending messages or setting access groups.
        byInstanceId(processInstanceId): ProcessApi.v1;

        // Returns process information such as its key, name, instance identifier, business key
        getProcessInfo(): ProcessInfo;

        // Returns information about the current user task, such as its key, name, identifier
        getUserTaskInfo(): UserTaskInfo;
    }
}

interface StartProcessOptions {
    // Optional business key for the new process instance
    businessKey?: string;

    // Optional process variables for the new process instance
    variables?: { [key: string]: string };
}

interface ProcessInfo {
    // Returns the process instance identifier
    id(): string;

    // Returns the process definition key
    definitionKey(): string;

    // Returns the process name, if set
    name(): string | null;

    // Returns the process business key, if set
    businessKey(): string | null;
}

interface UserTaskInfo {
    // Returns the user task identifier
    id(): string;

    // Returns the user task definition key
    definitionKey(): string;

    // Returns the user task name
    name(): string;
}

Execution context

The API is available from the object api.process.v1 and operates in the context of the current process. Process identifier:

• For platform-launched forms within a process — filled in automatically.

• For resumed processes (e.g. via the endpoint #/process) — the process instance identifier must be provided.

• For script tasks — required without exception.

---

Reference to another process

It is possible to reference another process, but caution is required — this operation is error-prone.

Each time, make sure the process identifier comes from a trusted source.

The API for such a case is available at:

api.process.v1.byInstanceId(processInstanceId: string)

where processInstanceId is the identifier of the process instance we want to reference.

Note: The function setAccessGroups() does not support calling from api.process.v1.byInstanceId.

Availability: The API is available only in:

• scripts,

• script validators,

• script tasks.

---

Usage examples

1. correlateMessage()

Sending a message named MESSAGE_NAME

function callService(context) {
  api.process.v1.correlateMessage("MESSAGE_NAME");
}

Sending a message with a process variable set

function callService(context) {
  api.process.v1.correlateMessage("MESSAGE_NAME", { "variable": "value" });
}

Sending a message to a specific process

function callService(context) {
  const processInstanceId = "...";
  api.process.v1.byInstanceId(processInstanceId).correlateMessage("MESSAGE_NAME");
}

Sending a message to a specific process with multiple variables

function callService(context) {
  const processInstanceId = "...";
  api.process.v1.byInstanceId(processInstanceId).correlateMessage("MESSAGE_NAME", { 
    "variableA": "value1",
    "variableB": "value2",
    "variableC": "value3"
  });
}

---

2. setAccessGroups()

Description of operation

The method grants additional access to display the case (process instance) in the cases list.

• The group must have the permission feature_process_list.

• The method granted beforehand; it overwrites all previously assigned groups.

If the group GROUP_TESTpreviously had access, and we run the code below, only the groups indicated will have access in the method (GROUP_1 and GROUP_2).

Usage example

function callService(context) {
  api.process.v1.setAccessGroups(["GROUP_1", "GROUP_2"]);
}

To reset the access groups, overwrite the current values with an empty list.

function callService(context) {
    // ...
    api.process.v1.setAccessGroups([])
    // ...
}

---

Starting a new process

The API also allows starting a new process. When using this functionality, you should take into account the possibility of scripts being called multiple times and ensure the operation is idempotent.

Be careful not to start multiple process instances as a result of repeated script execution (e.g. by a user refreshing the page, attaching the script multiple times, or attaching it to an event that can be triggered multiple times).

function callService(context) {
    // ...
    api.process.v1.startProcess(definitionKey: string, data: {businessKey?: string, variables: { [key: string]: string }})
    // ...
}

Usage examples

Starting a process with a business key and process variables:

function callService(context) {
  const processInstanceId = api.process.v1.startProcess("proces_demo", {
    businessKey: "demo_123",
    variables: {
      "variableA": "value1",
      "variableB": "value2"
    }
  });
}

Starting a process without additional parameters:

function callService(context) {
  const processInstanceId = api.process.v1.startProcess("proces_demo");
}

---

Retrieving process information

The API allows you to retrieve information about the current process, such as its key, name, instance identifier, or business key.

Usage examples

function callService(context) {
    const processInfo = api.process.v1.getProcessInfo();
    Logger.info("Get process info: {}", processInfo);

    return [{
        'processId': processInfo.id(),
        'processDefinitionKey': processInfo.definitionKey(),
        'processName': processInfo.name(),
        'processBusinessKey': processInfo.businessKey()
    }];
}

Retrieving user task information

The API also allows you to retrieve information about the current user task, such as its key, name, or identifier.

function callService(context) {
    const userTaskInfo = api.process.v1.getUserTaskInfo();
    Logger.info("Get user task info: {}", userTaskInfo);

    return [{
        'userTaskId': userTaskInfo.id(),
        'userTaskDefinitionKey': userTaskInfo.definitionKey(),
        'userTaskName': userTaskInfo.name()
    }];
}

---

Additional information

More details can be found in the section Case list configuration in the platform documentation.