> 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/budowanie-aplikacji/logika-biznesowa/scriptcode/skrypty-scriptservice/api-skryptow/uslugi-platformy/operacje-na-procesach.md). # Operacje i dostęp do danych procesu Interfejs `api.process.v1` udostępnia mechanizmy do interakcji z silnikiem procesowym (BPM) platformy Eximee. Pozwala on na asynchroniczne sterowanie przepływem procesu (poprzez wysyłanie wiadomości) oraz dynamiczne zarządzanie uprawnieniami do spraw na liście spraw użytkownika. ### API ```typescript interface ProcessApi { v1: { /* Wysyła wiadomości do procesu, * opcjonalnie można przekazać zmienne procesowe. */ correlateMessage(messageName: string, processVariables?: { [key: string]: string }); /* Ustawia listę grup, * które mają dostęp do instancji procesu na liście spraw */ setAccessGroups(groupNames: string[]); /* Startuje nowy proces na podstawie klucza definicji procesu. * Opcjonalnie można przekazać business key i zmienne procesowe. * Zwraca identyfikator instancji procesu. */ startProcess(definitionKey: string, data?: StartProcessOptions): string; /* Pozwala odwołać się do innego procesu na podstawie jego identyfikatora instancji. * Umożliwia wykonanie operacji na tym procesie, * takich jak wysyłanie wiadomości czy ustawianie grup dostępu. */ byInstanceId(processInstanceId): ProcessApi.v1; /* Zwraca informacje o procesie, * takie jak jego klucz, nazwa, identyfikator instancji, klucz biznesowy. */ getProcessInfo(): ProcessInfo; /* Zwraca informacje o aktualnym zadaniu użytkownika, * takie jak jego klucz, nazwa, identyfikator. */ getUserTaskInfo(): UserTaskInfo; // Zwraca listę incydentów instancji procesu (aktualnej lub wskazanej przez byInstanceId) getIncidents(): Incident[]; // Ponawia wykonanie external taska; retries określa liczbę ponowień (domyślnie 1) retryExternalTask(externalTaskId: string, retries?: number): void; } } interface StartProcessOptions { // Opcjonalny klucz biznesowy dla nowej instancji procesu businessKey?: string; // Opcjonalne zmienne procesowe dla nowej instancji procesu variables?: { [key: string]: string }; } interface ProcessInfo { // Zwraca identyfikator instancji procesu id(): string; // Zwraca klucz definicji procesu definitionKey(): string; // Zwraca nazwę procesu, jeśli została ustawiona name(): string | null; // Zwraca klucz biznesowy procesu, jeśli został ustawiony businessKey(): string | null; } interface UserTaskInfo { // Zwraca identyfikator zadania użytkownika id(): string; // Zwraca klucz definicji zadania użytkownika definitionKey(): string; // Zwraca nazwę zadania użytkownika name(): string; } interface Incident { // Zwraca identyfikator incydentu id(): string; // Zwraca typ incydentu: "failedJob", "failedExternalTask" lub typ niestandardowy incidentType(): string; // Zwraca identyfikator elementu, którego dotyczy incydent: external taska (dla "failedExternalTask") lub joba (dla "failedJob") configuration(): string | null; // Zwraca treść błędu incidentMessage(): string | null; // Zwraca datę i godzinę wystąpienia incydentu w formacie yyyy-MM-dd'T'HH:mm:ss.SSSZ, np. 2026-01-23T14:42:45.000+0200 incidentTimestamp(): string; // Zwraca identyfikator definicji procesu processDefinitionId(): string | null; // Zwraca identyfikator instancji procesu processInstanceId(): string | null; // Zwraca identyfikator wykonania (ścieżki) w instancji procesu executionId(): string | null; // Zwraca krok procesu, na którym widoczny jest incydent activityId(): string | null; // Zwraca krok procesu, na którym faktycznie wystąpił błąd failedActivityId(): string | null; // Zwraca identyfikator incydentu, który bezpośrednio spowodował ten incydent causeIncidentId(): string; // Zwraca identyfikator incydentu źródłowego; jeśli jest równy id(), ten incydent jest incydentem źródłowym rootCauseIncidentId(): string; // Zwraca identyfikator definicji joba (dla "failedJob") jobDefinitionId(): string | null; // Zwraca identyfikator tenanta, jeśli używany jest multi-tenancy tenantId(): string | null; // Zwraca notatkę dodaną ręcznie do incydentu annotation(): string | null; } ``` ### Kontekst działania API jest dostępne z obiektu `api.process.v1` i działa w kontekście aktualnego procesu.\ Identyfikator procesu: * W przypadku formularzy uruchamianych platformowo w ramach procesu — uzupełniany **automatycznie**. * W przypadku wznawianych procesów (np. przez endpoint `#/process`) — należy przekazać identyfikator instancji procesu. * W przypadku zadań skryptowych — **bezwarunkowo wymagany**. *** ### Odwołanie do innego procesu | Metoda | Opis | | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | `byInstanceId(processInstanceId)` | Zmienia kontekst wywołania na wskazaną instancję procesu. Zwraca obiekt pozwalający na wywołanie metod procesowych (np. `correlateMessage`). | {% hint style="danger" %} **Ostrzeżenie o bezpieczeństwie:** Odwoływanie się do zewnętrznej instancji procesu jest operacją błędogenną. Należy każdorazowo upewnić się, że przekazywany identyfikator `processInstanceId` pochodzi z **zaufanego źródła** (np. z zabezpieczonego rejestru lub wewnętrznej zmiennej). {% endhint %} API dla takiego przypadku dostępne jest pod: ```typescript api.process.v1.byInstanceId(processInstanceId: string) ``` gdzie `processInstanceId` to identyfikator instancji procesu, do którego chcemy się odwołać. {% hint style="warning" %} **Uwaga:** Funkcja `setAccessGroups()` **nie wspiera** wywołania z `api.process.v1.byInstanceId`. {% endhint %} {% hint style="info" %} **Dostępność:** API jest dostępne jedynie w: * skryptach, * walidatorach skryptowych, * zadaniach skryptowych. {% endhint %} ## Przykłady użycia ### 1. `correlateMessage()` | Metoda | Opis | | --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | `correlateMessage(messageName, [processVariables])` | Wysyła wiadomość o nazwie `messageName`. Opcjonalnie przyjmuje mapę klucz-wartość reprezentującą zmienne procesowe do zaktualizowania. | **Wysyłka wiadomości o nazwie `MESSAGE_NAME`** ```typescript function callService(context) { api.process.v1.correlateMessage("MESSAGE_NAME"); } ``` **Wysyłka wiadomości z ustawieniem zmiennej procesowej** ```typescript function callService(context) { api.process.v1.correlateMessage("MESSAGE_NAME", { "zmienna": "wartość" }); } ``` **Wysyłka wiadomości do określonego procesu** ```typescript function callService(context) { const processInstanceId = "..."; api.process.v1.byInstanceId(processInstanceId).correlateMessage("MESSAGE_NAME"); } ``` **Wysyłka wiadomości do określonego procesu z wieloma zmiennymi** ```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()` | Metoda | Opis | | ----------------------------------------- | --------------------------------------------------------------------------- | | `permissions.setAccessGroups(groupNames)` | Ustawia listę grup, które mają dostęp do instancji procesu na liście spraw. | **Opis działania** Metoda **nadaje dodatkowy dostęp** do wyświetlania sprawy (instancji procesu) na liście spraw. * Grupa musi mieć wcześniej nadane uprawnienie `feature_process_list`. * Metoda **nadpisuje wszystkie wcześniej przypisane grupy**. {% hint style="warning" %} Jeśli wcześniej dostęp miała grupa `GROUP_TEST`, a wykonamy poniższy kod, dostęp będą miały **tylko grupy wskazane** w metodzie (`GROUP_1` i `GROUP_2`). {% endhint %} **Przykład użycia** ```typescript function callService(context) { api.process.v1.setAccessGroups(["GROUP_1", "GROUP_2"]); } ``` Aby zresetować grupy dostępu, należy nadpisać dotychczasowe wartości pustą listą. ```typescript function callService(context) { // ... api.process.v1.setAccessGroups([]) // ... } ``` *** ### Startowanie nowego procesu API pozwala również na wystartowanie nowego procesu. Wykorzystując tę funkcjonalność, należy uwzględnić możliwość wielorazowego wołania się skryptów i zapewnić idempotentność operacji. | Metoda | Opis | | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `startProcess(definitionKey, [data])` | Startuje nowy proces na podstawie klucza definicji procesu, opcjonalnie można przekazać business key i zmienne procesowe. Zwraca identyfikator instancji procesu. | Należy zachować ostrożność, aby nie wystartować wielu instancji procesu w wyniku wielokrotnego wywołania skryptu (np. przez użytkownika odświeżającego stronę, podpięcia wielokrotnego skryptu lub podpięcia pod zdarzenie mogące się zawołać wielokrotnie). ```typescript function callService(context) { // ... api.process.v1.startProcess(definitionKey: string, data: {businessKey?: string, variables: { [key: string]: string }}) // ... } ``` **Przykłady użycia** Wystartowanie procesu z business key i zmiennymi procesowymi: ```typescript function callService(context) { const processInstanceId = api.process.v1.startProcess("proces_demo", { businessKey: "demo_123", variables: { "zmiennaA": "wartość1", "zmiennaB": "wartość2" } }); } ``` Wystartowanie procesu bez dodatkowych parametrów: ```typescript function callService(context) { const processInstanceId = api.process.v1.startProcess("proces_demo"); } ``` ### Pobieranie informacji o procesie API umożliwia pobranie informacji o aktualnym procesie, takich jak jego klucz, nazwa, identyfikator instancji czy klucz biznesowy. | Metoda | Opis | | ------------------ | ---------------------------------------------------------------------------------------------------- | | `getProcessInfo()` | Zwraca informacje o procesie, takie jak jego klucz, nazwa, identyfikator instancji, klucz biznesowy. | **Przykłady użycia** ```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() }]; } ``` ### Pobieranie informacji o zadaniu użytkownika API umożliwia również pobranie informacji o aktualnym zadaniu użytkownika, takich jak jego klucz, nazwa czy identyfikator. | Metoda | Opis | | ------------------- | ---------------------------------------------------------------------------------------------- | | `getUserTaskInfo()` | Zwraca informacje o aktualnym zadaniu użytkownika, takie jak jego klucz, nazwa, identyfikator. | ```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() }]; } ``` *** #### Pobieranie incydentów procesu Metoda `getIncidents()` zwraca listę incydentów instancji procesu. Incydent powstaje, gdy silnik procesów nie może wykonać kroku procesu, np. po wyczerpaniu liczby ponowień zadania asynchronicznego lub external taska. Jeśli instancja nie ma incydentów, metoda zwraca pustą listę. * `api.process.v1.getIncidents()` — zwraca incydenty aktualnej instancji procesu. * `api.process.v1.byInstanceId(processInstanceId).getIncidents()` — zwraca incydenty wskazanej instancji procesu. Struktura zwracanego obiektu jest opisana w interfejsie `Incident` w sekcji [API](#api) i odpowiada obiektowi `IncidentDto` z [REST API EximeeBPMS](https://docs.eximeebpms.org/rest/1.0/#tag/Incident/operation/getIncidents). Podpowiedzi składni w edytorze skryptów obejmują wywołanie metody, ale nie podpowiadają metod zwracanych obiektów. {% hint style="info" %} Metoda `configuration()` zwraca identyfikator elementu, którego dotyczy incydent: dla typu `failedExternalTask` jest to identyfikator external taska, który przekazujesz do metody `retryExternalTask()`. Dla typu `failedJob` jest to identyfikator joba — ponawianie jobów nie jest obecnie dostępne w API. {% endhint %} **Przykłady użycia** Zwrócenie liczby incydentów aktualnej instancji procesu: ```typescript function callService(context) { const incidents = api.process.v1.getIncidents(); return [{ 'incidentsCount': incidents.length }]; } ``` Zwrócenie liczby incydentów procesu, którego identyfikator przekazano do skryptu w parametrze wejściowym `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 }]; } ``` *** #### Ponawianie external taska Metoda `retryExternalTask(externalTaskId, retries)` ustawia liczbę ponowień external taska, dzięki czemu silnik procesów ponownie podejmuje jego wykonanie, a powiązany incydent zostaje rozwiązany. * `externalTaskId` — identyfikator external taska. Dla incydentu typu `failedExternalTask` zwraca go metoda `configuration()`. * `retries` — liczba ponowień. Parametr jest opcjonalny, domyślna wartość to `1`. Wartość musi być większa lub równa 1, podanie mniejszej wartości kończy się błędem. {% hint style="warning" %} Przed ponowieniem upewnij się, że przyczyna błędu została usunięta (np. usługa zewnętrzna jest ponownie dostępna). W przeciwnym razie external task zakończy się kolejnym błędem i incydent powstanie ponownie. {% endhint %} **Przykłady użycia** Ponowienie wszystkich external tasków z incydentami we wskazanej instancji procesu: ```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())); } ``` Ponowienie external taska z trzema próbami wykonania: ```typescript function callService(context) { const externalTaskId = "..."; api.process.v1.retryExternalTask(externalTaskId, 3); } ``` {% hint style="info" %} **Zapoznaj się:** Istotne informacje znajdziesz w sekcji [**Konfiguracja listy spraw**](/budowanie-aplikacji/interfejs-uzytkownika/eximee-dashboard/konfiguracja/lista-spraw.md) oraz [**Uprawnienia Eximee Dashboard**](/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/budowanie-aplikacji/logika-biznesowa/scriptcode/skrypty-scriptservice/api-skryptow/uslugi-platformy/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.