# Operacje i dostęp do danych procesu ## Operacje i dostęp do danych procesu *** ### 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; } } 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; } ``` #### 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 Istnieje możliwość odwołania się do **innego procesu**, jednak należy zachować ostrożność — ta operacja jest **błędogenna**. Każdorazowo należy upewnić się, że identyfikator procesu pochodzi z **zaufanego źródła**. 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()` **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()` **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. 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. **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. ```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() }]; } ``` *** #### Dodatkowe informacje Więcej szczegółów znajdziesz w sekcji **Konfiguracja listy spraw** w dokumentacji platformy. --- # 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/budowanie-aplikacji/logika-biznesowa/scriptcode/skrypty-scriptservice/api-skryptow/operacje-i-dostep-do-danych-procesu.md?ask= ``` 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.