# Process data operations and access

## Process data operations and access

***

### API

```typescript
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:

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

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

{% hint style="warning" %}
**Note:** The function `setAccessGroups()` **does not support** calling from `api.process.v1.byInstanceId`.
{% endhint %}

{% hint style="info" %}
**Availability:** The API is available only in:

* scripts,
* script validators,
* script tasks.
  {% endhint %}

***

### Usage examples

#### 1. `correlateMessage()`

**Sending a message named `MESSAGE_NAME`**

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

**Sending a message with a process variable set**

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

**Sending a message to a specific process**

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

**Sending a message to a specific process with multiple variables**

```typescript
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**.

{% hint style="warning" %}
If the group `GROUP_TEST`previously had access, and we run the code below, only the groups indicated **will have access** in the method (`GROUP_1` and `GROUP_2`).
{% endhint %}

**Usage example**

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

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

```typescript
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).

```typescript
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:

```typescript
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:

```typescript
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**

```typescript
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.

```typescript
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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.eximee.com/documentation/documentation-en/budowanie-aplikacji/logika-biznesowa/scriptcode/skrypty-scriptservice/api-skryptow/operacje-i-dostep-do-danych-procesu.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.