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 case list
        setAccessGroups(groupNames: string[]);

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

        // Allows referring to another process by its instance ID. Enables performing operations on that process, such as sending messages or setting access groups.
        byInstanceId(processInstanceId): ProcessApi.v1;

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

        // Returns information about the current user task, such as its key, name, ID
        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 ID
    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 ID
    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 works in the context of the current process.\nProcess ID:

• In the case of platform-launched forms within a process — filled in automatically.
• In the case of resumed processes (e.g. via the endpoint #/process) — the process instance ID must be provided.
• In the case of script tasks — absolutely required.

---

Referring to another process

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

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

The API for such a case is available at:

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

where processInstanceId is the ID of the process instance we want to refer to.

Note: The function setAccessGroups() does not support calls 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", { "zmienna": "wartość" });
}

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", { 
    "zmiennaA": "wartość1",
    "zmiennaB": "wartość2",
    "zmiennaC": "wartość3"
  });
}

---

2. setAccessGroups()

How it works

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

• The group must previously have been granted the permission feature_process_list.
• The method overwrites all previously assigned groups.

If the group previously had access GROUP_TEST, and we run the code below, access will be granted to only the groups specified 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, 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 may 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: {
      "zmiennaA": "wartość1",
      "zmiennaB": "wartość2"
    }
  });
}

Starting a process without additional parameters:

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

---

Retrieving process information

The API allows retrieving information about the current process, such as its key, name, instance ID, 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 retrieving information about the current user task, such as its key, name, or ID.

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.