Operacje i dostęp do danych procesu

Operacje i dostęp do danych procesu

---

API

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:

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

gdzie processInstanceId to identyfikator instancji procesu, do którego chcemy się odwołać.

Uwaga: Funkcja setAccessGroups() nie wspiera wywołania z api.process.v1.byInstanceId.

Dostępność: API jest dostępne jedynie w:

• skryptach,

• walidatorach skryptowych,

• zadaniach skryptowych.

---

Przykłady użycia

1. correlateMessage()

Wysyłka wiadomości o nazwie MESSAGE_NAME

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

Wysyłka wiadomości z ustawieniem zmiennej procesowej

function callService(context) {
  api.process.v1.correlateMessage("MESSAGE_NAME", { "zmienna": "wartość" });
}

Wysyłka wiadomości do określonego procesu

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

Wysyłka wiadomości do określonego procesu z wieloma zmiennymi

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.

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

Przykład użycia

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

Aby zresetować grupy dostępu, należy nadpisać dotychczasowe wartości pustą listą.

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

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:

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:

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

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.

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.