> For the complete documentation index, see [llms.txt](https://docs.eximee.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.eximee.com/documentation/documentation-en/budowanie-aplikacji/logika-biznesowa/scriptcode/skrypty-scriptservice/api-skryptow/operacje-i-dostep-do-danych-procesu.md).

# Process operations and data 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 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:

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

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

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

**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", { 
    "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**.

{% hint style="warning" %}
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`).
{% 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, 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).

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

Starting a process without additional parameters:

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

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

```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
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` 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>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.