> 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/platform-services/operacje-na-procesach.md). # Process operations and data access Interface `api.process.v1` provides mechanisms for interaction with the Eximee platform process engine (BPM). It allows asynchronous control of process flow (by sending messages) and dynamic management of permissions to cases on the user's case list. ### API ```typescript interface ProcessApi { v1: { /* Sends messages to the process, * optionally process variables can be passed. */ correlateMessage(messageName: string, processVariables?: { [key: string]: string }); /* Sets the list of groups, * that have access to the process instance on the case list */ setAccessGroups(groupNames: string[]); /* Starts a new process based on the process definition key. * Optionally, business key and process variables can be passed. * Returns the process instance identifier. */ startProcess(definitionKey: string, data?: StartProcessOptions): string; /* Allows referring to another process based on its instance identifier. * Enables operations on this process, * such as sending messages or setting access groups. */ byInstanceId(processInstanceId): ProcessApi.v1; /* Returns information about the process, * 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; // Returns a list of process instance incidents (current or specified by byInstanceId) getIncidents(): Incident[]; // Retries an external task; retries specifies the number of retries (default 1) retryExternalTask(externalTaskId: string, retries?: number): void; } } 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; } interface Incident { // Returns the incident identifier id(): string; // Returns the incident type: "failedJob", "failedExternalTask" or a custom type incidentType(): string; // Returns the identifier of the element the incident concerns: an external task (for "failedExternalTask") or a job (for "failedJob") configuration(): string | null; // Returns the error message incidentMessage(): string | null; // Returns the date and time when the incident occurred in the format yyyy-MM-dd'T'HH:mm:ss.SSSZ, e.g. 2026-01-23T14:42:45.000+0200 incidentTimestamp(): string; // Returns the process definition identifier processDefinitionId(): string | null; // Returns the process instance identifier processInstanceId(): string | null; // Returns the execution (path) identifier in the process instance executionId(): string | null; // Returns the process activity where the incident is visible activityId(): string | null; // Returns the process activity where the error actually occurred failedActivityId(): string | null; // Returns the identifier of the incident that directly caused this incident causeIncidentId(): string; // Returns the identifier of the root cause incident; if it equals id(), this incident is the root cause incident rootCauseIncidentId(): string; // Returns the job definition identifier (for "failedJob") jobDefinitionId(): string | null; // Returns the tenant identifier, if multi-tenancy is used tenantId(): string | null; // Returns the note manually added to the incident annotation(): string | null; } ``` ### 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-started forms within a process — filled in **automatically**. * For resumed processes (e.g. via endpoint `#/process`) — you need to pass the process instance identifier. * For script tasks — **unconditionally required**. *** ### Referencing another process | method | Description | | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | `byInstanceId(processInstanceId)` | Changes the call context to the specified process instance. Returns an object allowing process methods to be called (e.g. `correlateMessage`). | {% hint style="danger" %} **Security warning:** Referencing an external process instance is an error-prone operation. Make sure each time that the passed identifier `processInstanceId` comes from **a trusted source** (e.g. from a secured registry or an internal variable). {% endhint %} The API for this 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()` | method | Description | | --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | | `correlateMessage(messageName, [processVariables])` | Sends a message named `messageName`. Optionally accepts a key-value map representing process variables to update. | **Sending a message named `MESSAGE_NAME`** ```typescript function callService(context) { api.process.v1.correlateMessage("MESSAGE_NAME"); } ``` **Sending a message while setting a process variable** ```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()` | method | Description | | ----------------------------------------- | ---------------------------------------------------------------------------------- | | `permissions.setAccessGroups(groupNames)` | Sets the list of groups that have access to the process instance on the case list. | **Operation description** method **grants additional access** to view the case (process instance) on the case list. * The group must have previously been granted permission `feature_process_list`. * method **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 **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 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. Using this functionality, you should consider the possibility of scripts being called multiple times and ensure the operation is idempotent. | method | Description | | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `startProcess(definitionKey, [data])` | Starts a new process based on the process definition key, optionally business key and process variables can be passed. Returns the process instance identifier. | 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 identifier, or business key. | method | Description | | ------------------ | ------------------------------------------------------------------------------------------------ | | `getProcessInfo()` | Returns information about the process, such as its key, name, instance identifier, 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 identifier. | method | Description | | ------------------- | ----------------------------------------------------------------------------------- | | `getUserTaskInfo()` | Returns information about the current user task, such as its key, name, 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() }]; } ``` *** #### Retrieving process incidents method `getIncidents()` returns a list of process instance incidents. An incident is created when the process engine cannot execute a process step, e.g. after exhausting the number of retries of an asynchronous task or external task. If the instance has no incidents, the method returns an empty list. * `api.process.v1.getIncidents()` — returns incidents of the current process instance. * `api.process.v1.byInstanceId(processInstanceId).getIncidents()` — returns incidents of the specified process instance. The structure of the returned object is described in the `Incident` section [API](#api) and corresponds to the object `IncidentDto` from [EximeeBPMS REST API](https://docs.eximeebpms.org/rest/1.0/#tag/Incident/operation/getIncidents). Syntax hints in the script editor include the method call, but do not suggest methods of returned objects. {% hint style="info" %} method `configuration()` returns the identifier of the element the incident concerns: for type `failedExternalTask` this is the identifier of the external task that you pass to the method `retryExternalTask()`. For type `failedJob` this is the job identifier — retrying jobs is not currently available in the API. {% endhint %} **Usage examples** Returning the number of incidents of the current process instance: ```typescript function callService(context) { const incidents = api.process.v1.getIncidents(); return [{ 'incidentsCount': incidents.length }]; } ``` Returning the number of incidents of the process whose identifier was passed to the script in the input parameter `processInstanceId`: ```typescript function callService(context) { const processInstanceId = context.getFirstParameter('processInstanceId'); const incidents = api.process.v1.byInstanceId(processInstanceId).getIncidents(); incidents.forEach(incident => { Logger.info("Incident {} ({}) on activity {}: {}", incident.id(), incident.incidentType(), incident.failedActivityId(), incident.incidentMessage()); }); return [{ 'incidentsCount': incidents.length }]; } ``` *** #### Retrying an external task method `retryExternalTask(externalTaskId, retries)` sets the number of retries of an external task, so that the process engine retries its execution and the related incident is resolved. * `externalTaskId` — external task identifier. For incident type `failedExternalTask` it is returned by method `configuration()`. * `retries` — number of retries. The parameter is optional, default value is `1`. The value must be greater than or equal to 1; providing a smaller value results in an error. {% hint style="warning" %} Before retrying, make sure the cause of the error has been removed (e.g. the external service is available again). Otherwise, the external task will fail again and the incident will reappear. {% endhint %} **Usage examples** Retrying all external tasks with incidents in the specified process instance: ```typescript function callService(context) { const processInstanceId = context.getFirstParameter('processInstanceId'); const incidents = api.process.v1.byInstanceId(processInstanceId).getIncidents(); incidents .filter(incident => incident.incidentType() === 'failedExternalTask') .forEach(incident => api.process.v1.retryExternalTask(incident.configuration())); } ``` Retrying an external task with three execution attempts: ```typescript function callService(context) { const externalTaskId = "..."; api.process.v1.retryExternalTask(externalTaskId, 3); } ``` {% hint style="info" %} **See also:** Important information can be found in the section [**Case list configuration**](/documentation/documentation-en/budowanie-aplikacji/interfejs-uzytkownika/eximee-dashboard/konfiguracja/lista-spraw.md) and [**Eximee Dashboard permissions**](/documentation/documentation-en/budowanie-aplikacji/interfejs-uzytkownika/eximee-dashboard/konfiguracja/uprawnienia.md). {% endhint %} --- # 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 by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.eximee.com/documentation/documentation-en/budowanie-aplikacji/logika-biznesowa/scriptcode/skrypty-scriptservice/api-skryptow/platform-services/operacje-na-procesach.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. 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.