Operations and access to process data

Operations and access to process data

---

API

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

  setAccessGroups(groupNames: string[]) 
  // Sets the list of groups that have access to the process instance on the task list
}

Execution context

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

• In the case of platform-launched forms within a process — filled automatically.

• In the case of resumed processes (e.g. via the #/process) — you should pass the variable router_process_id (must be mapped by injectable fields).

• In the case of script tasks — unconditionally required.

---

Reference to another process

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

Each time you must ensure that 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 you 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 setting a process variable

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()

Description of operation

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

• A group must have previously been granted the permission feature_process_list.

• The method overwrites all previously assigned groups.

If previously the group GROUP_TEST, and we execute the code below, access will be granted only to the groups specified in the method (GROUP_1 and GROUP_2).

Usage example

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

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

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

---

Additional information

You can find more details in the Task list configuration section of the platform documentation.