> 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/zadanie-skryptowe-scripttask/api-zadan-skryptowych.md).

# API Zadań skryptowych

\
Platforma dostarcza możliwość tworzenia logiki zadań skryptowych handlerów z poziomu Eximee Designer. Projektant procesu musi jedynie napisać logikę handlera oraz podpiąć go w procesie.

## Tworzenie zadania skryptowego <a href="#zadanieskryptowe-tworzeniezadaniaskryptowego" id="zadanieskryptowe-tworzeniezadaniaskryptowego"></a>

Zadania skryptowe możemy tworzyć i edytować za pomocą aplikacji Eximee Designer. W tym celu należy w module **Biblioteka** wybrać zakładkę **Zadania skryptowe**:

<figure><img src="https://1082717226-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F2CssJT0zIo4SJQLbSZ6l%2Fuploads%2FYw3d6gs72b0Ijnh8BhYH%2Fimage.png?alt=media&amp;token=7621e387-2eca-47c4-ba77-5141a61b665b" alt=""><figcaption><p><em><strong>Ilustracja 1.</strong> Okno zakładki zadań skryptowych</em></p></figcaption></figure>

Szczegółowy opis tworzenia skryptów dostępny jest w: [Zadania skryptowe](https://docs.eximee.com/budowanie-aplikacji/logika-biznesowa/scriptcode/zadanie-skryptowe-scripttask.md).

### API handlerów <a href="#zadanieskryptowe-apihandlerow" id="zadanieskryptowe-apihandlerow"></a>

```typescript
interface Task {
   getVariable(name): string;                                 // Pobieranie zmiennej procesu o identyfikatorze wskazanym w parametrze
   getAllVariables(): {[key: string]: string};                // Pobieranie wszystkich zmiennych w procesie
   getProcessIntanceId(): string;                             // Zwraca identyfikator instancji procesu
}
 
interface Context {
   complete(variables: [key: string]: string, modelChanges?: [key: string]: string): void; // Zakończenie zadania i przekazanie do procesu zmiennych wskazanych w parametrze oraz opcjonalnie zmian w modelu danych (wartość null przy kluczu czyści ten klucz)
   handleFailure(cause: string): void;                        // Zgłoszenie na zadaniu incydentu (np. błąd systemowy) wraz z określeniem powodu wskazanego w parametrze (proces zatrzymuje się do czasu interwencji)    
   handleBpmnError(errorCode: string, cause?: string): void;  // Zgłoszenie na zadaniu przewidzianego błędu biznesowego wraz z kodem błędu oraz powodem wskazanym w parametrze (uruchamiana jest ścieżka obsługi błędu w BPMN)
    
   // Deprected
   getModel(String processInstanceId, List<String> fieldsNames): Map<String, String> // Wywołanie modelu danych podając id instancji procesu oraz listę kluczy, których wartość chcemy pobrać.
                                                                                     // Metoda przestarzała. Należy używać api.model
}
 
interface Logger {
    info(message: string, ...args: any);                      // Logowanie na poziomie INFO                
    debug(message: string, ...args: any);                     // Logowanie na poziomie DEBUG
    warn(message: string, ...args: any);                      // Logowanie na poziomie WARN
    error(message: string, ...args: any);                     // Logowanie na poziomie ERROR
    trace(message: string, ...args: any);                     // Logowanie na poziomie TRACE
}
 
function nonsensitive(arg: any): String;
 
function handle(task: Task, context: Context): void {}


```

{% hint style="info" %}
Ustawienie listy grup, które będą miały dostęp do instancji procesu na liście spraw

[Operacje i dostęp do danych procesu](https://github.com/Consdata/eximee-docs/tree/main/budowanie-aplikacji/logika-biznesowa/scriptcode/skrypty-scriptservice/api-skryptow/operacje-i-dostep-do-danych-procesu.md)
{% endhint %}

### Przykładowe zadania skryptowe <a href="#zadanieskryptowe-przykladowezadaniaskryptowe" id="zadanieskryptowe-przykladowezadaniaskryptowe"></a>

Skrypt pobiera zmienną o identyfikatorze „testVariable”, mnoży ją przez samą siebie, a wynik przypisuje do nowej zmiennej „result”:

```javascript
function handle(task, context) {
    Logger.info("Rozpoczęcie zadania skryptowego nazwaSensytywna={}, nazwaNieSensytywna={}", 'TAJNE_DANE', nonsensitive('NIETAJNE_DANE'))
 
    const testVariableNumber = task.getVariable('testVariable');
    const testVariablePower = testVariableNumber * testVariableNumber;
     
    Logger.info("Zakończenie zadania skryptowego")
    context.complete({'result': testVariablePower});
 }
```

### Wywołanie usług Rest w zadaniu skryptowym <a href="#zadanieskryptowe-wywolanieuslugrestwzadaniuskryptowym" id="zadanieskryptowe-wywolanieuslugrestwzadaniuskryptowym"></a>

Dokumentacja wywołania: [\[Rest\] Wołanie zewnętrznych usług RESTowych (ScriptCode)](https://docs.eximee.com/budowanie-aplikacji/logika-biznesowa/scriptcode/restapi-integracje-z-zewnetrznymi-systemami.md)

{% hint style="danger" %}
Jedyną zmianą co do powyższej dokumentacji jest plik konfiguracyjny.

Ten dla ScriptCode Handler nazywa się **script-handler-api.xml** i znajduję się w katalogu **`/etc/eximee/webforms/script-handler-config`**
{% endhint %}

Przykład zadania skryptowego z wywołaniem zewnętrznej usługi REST:

```typescript
function handle(task, context) {
    // Pobranie zmiennej procesowej o kluczu "testVariable"
    let value = task.getVariable('testVariable');
     
    // Pobranie zmiennej procesowej o kluczu "result"
    let result = task.getVariable('result');
 
    if (value == null || isNaN(value)) {
        // Zgłoszenie na zadaniu błędu wraz z kodem błędu "errorCode"
         context.handleBpmnError("errorCode", "Brak wartości dla zmiennej procesowej o kluczu testVariable");
    }
 
    value = value * 5
    result = result * 5
    Logger.info("Passed: [value={}, result={}]", value, result);
          
    try {
        let response = api.rest.v1.get("questionnaire", {}, {});
 
        Logger.info("Task ended successfully");
        context.complete({'variable1': value, 'variable2': result, 'Questionnaires': response.body});
    }
    catch(e) {
        Logger.warn("Exception occured: {}", e.message);
        context.handleFailure("Failed to retrieve questionnaire list " + e.message);
    }      
}
```

### Pobieranie konfiguracji aplikacji biznesowej <a href="#zadanieskryptowe-pobieraniekonfiguracjiaplikacjibiznesowej" id="zadanieskryptowe-pobieraniekonfiguracjiaplikacjibiznesowej"></a>

Dokumentacja wywołania: [Skrypty (scriptService)#Pobieraniekonfiguracjiaplikacji](https://docs.eximee.com/budowanie-aplikacji/logika-biznesowa/scriptcode/skrypty-scriptservice/api-skryptow.md#skrypty-scriptservice-pobieraniekonfiguracjiaplikacji)

Przykład zadania skryptowego z pobraniem konfiguracji:

```javascript
function handle(task, context) {
    // Pobranie zmiennych z konfiguracji
    const skipTask = api.config.v1.get("script.task.skip.task")
    const titleName = api.config.v1.getOrDefault("script.task.title.name", "Domyślny tytuł")
     
    // Zakończenie zadania i przekazanie zmiennych (skipTask, titleName) do procesu
    context.complete({'skipTask': skipTask, 'titleName': titleName});
}
```

### Wywołanie Eximee Status w ScriptCode Handlerze <a href="#zadanieskryptowe-wywolanieeximeestatuswscriptcodehandlerze" id="zadanieskryptowe-wywolanieeximeestatuswscriptcodehandlerze"></a>

{% hint style="danger" %}
Aby wywołanie działało poprawnie należy uzupełnić parametr EXIMEE\_STATUS\_URL wskazujący na api eximee-status.

Metody wywołujące eximee-status wymagają zmiennej procesowej **statusId**, która powinna zawierać numer wniosku, dla którego ma zajść wskazana aktualizacja.
{% endhint %}

#### Status API <a href="#zadanieskryptowe-statusapi" id="zadanieskryptowe-statusapi"></a>

```typescript
interface EximeeStatusClient {
   updateStatus(statusName: string, statusDescription: string): void;   // Aktualizacja nazwy oraz opisu statusu
   updateMetadata(metadata: string): void;                               // Aktualizacja metadanych wniosku
   getMetadata(): Object;                                               // Pobranie metadanych wniosku
   getClientFormsBasicInfo(): Object;                                   // Pobranie listy statusów wniosków dla klienta zalogowanego (Metoda dostępna od wersji 4.154.0. Klient musi być zalogowany, aby funkcjonalność działała.)
 }
```

Przykład ScriptCodeHandler z wywołaniem eximee-status:

```javascript
function handle(task, context) {
    try {
        api.status.v1.updateStatus("NEW_STATUS", "STATUS_DESC");
 
        Logger.info("Task ended successfully");
        context.complete({});
    }
    catch(e) {
        Logger.warn("Exception occured: {}", e.message);
        context.handleFailure("Failed to retrieve questionnaire list " + e.message);
    }      
}
```

### Pobieranie zawartości Treści <a href="#zadanieskryptowe-pobieraniezawartoscitresci" id="zadanieskryptowe-pobieraniezawartoscitresci"></a>

{% hint style="info" %}
Funkcjonalność dostępna od wersji platformy: **3.332.0**
{% endhint %}

Z poziomu zadania skryptowego można pobrać zawartość artefaktu **Treść** (TextContent) utworzonego w **Eximee Designer**, wykorzystując do tego funkcję: `api.repository.v1.textContent`. Funkcja ta zwraca obiekt, który posiada treści dla każdego ze zdefiniowanych tłumaczeń. By pobrać treść dla danego tłumaczenia używamy funkcji `language`. Przykład użycia:

```javascript
const nazwaArtefaktu = "stopka";
const wersjaArtefakut = "*";
const język = "pl";
  
const artefaktTresci = api.repository.v1.textContent(nazwaArtefaktu, wersjaArtefaktu);
const stopkaPl = artefaktTresci.language(jezyk).text();
```

{% hint style="danger" %}

1. Funkcja **`textContent`** rzuca wyjątek jeśli nie znajdzie artefaktu o podanych parametrach.
2. Funkcja **`language`** rzuca wyjątek jeśli nie znajdzie tłumaczenia w podanym języku.
   {% endhint %}

Jeśli nie mamy pewności, że podane przez nas parametry są prawidłowe, możemy obsłużyć wyjątki używając **try catch**:

```javascript
const nazwaArtefaktu = "stopka";
const wersjaArtefaktu = "*";
const jezyk = "pl";
  
let artefaktTresci;
try {
    artefaktTresci = api.repository.v1.textContent(nazwaArtefaktu, wersjaArtefaktu);
} catch (error) {
    context.handleFailure("Brak artefaktu o nazwie: " + nazwaArtefaktu + " i wersji: " + wersjaArtefaktu);
    return;
}
  
let stopkaPl;  
try {
    stopkaPl = artefaktTresci.language(jezyk).text(); 
} catch (error) {
    context.handleFailure("W artefakcie nie znaleziono tłumaczenia dla języka: " + jezyk);
    return;
}
 
context.complete({'output': stopkaPl});
```

### Model danych

Więcej informacji w [API modelu danych](https://docs.eximee.com/budowanie-aplikacji/model-danych/wykorzystanie-modelu-danych/api-modelu-danych.md)

### Zapisanie danych w modelu danych

W zadaniach skryptowych możemy zapisać dane do modelu za pomocą metody 'complete', pierwszy parametr zapisuje dane do procesu, a drugi parametr zapisuje dane do modelu:

{% hint style="warning" %}
Klucz modelu musi istnieć w modelu danych, aby dane zostały poprawnie zapisane.
{% endhint %}

```js
function handle(task, context) {
    const branchId = task.getVariable('branchId');
    const isDocumentChangedRequired = task.getVariable('isDocumentChangedRequired');
    const documentsNotes = task.getVariable('documentsNotes');
 
    let modelUpdate = { "Ugoda.Adres.Oddzial": branchId, "Ugoda.CzyWymaganaZmianaTresciUmowy": isDocumentChangedRequired }
 
    if (isDocumentChangedRequired == "true") {
        modelUpdate['Ugoda.Uwagi'] = documentsNotes
    }
    context.complete({}, modelUpdate);
}
```

### Czyszczenie klucza modelu danych

Wyczyszczenie klucza usuwa wartości zapisane w modelu pod tym kluczem oraz we wszystkich jego węzłach podrzędnych. Można wyczyścić pole, tablicę lub węzeł z polami podrzędnymi, również zagnieżdżony. Więcej informacji o tych elementach znajduje się na stronie [Struktura modelu danych](https://docs.eximee.com/budowanie-aplikacji/model-danych/struktura-modelu-danych.md).

Aby wyczyścić klucz, należy w drugim parametrze metody `complete` przypisać mu wartość `null`:

```js
function handle(task, context) {
    // Wyczyszczenie tablicy zobowiązań i danych wnioskodawcy
    context.complete({}, {
        "kredyt.zobowiazania": null,
        "kredyt.wnioskodawca": null
    });
}
```

#### Odczyt po wyczyszczeniu

Po wyczyszczeniu klucz jest odczytywany tak samo jak klucz, pod którym nigdy nie zapisano wartości:

| Klucz                                                  | Odczyt po wyczyszczeniu                                                         |
| ------------------------------------------------------ | ------------------------------------------------------------------------------- |
| Pole z wartością domyślną, bez innego źródła danych    | wartość domyślna pola                                                           |
| Pole bez wartości domyślnej i bez innego źródła danych | pusty tekst                                                                     |
| Tablica bez innego źródła danych                       | tablica bez elementów                                                           |
| Pole lub tablica z innym źródłem danych                | wartość z tego źródła                                                           |
| Węzeł z polami podrzędnymi                             | wartości poszczególnych pól i tablic podrzędnych, zgodnie z powyższymi regułami |

Czyszczenie obejmuje wyłącznie wartości zapisane w modelu, czyli w źródle danych typu **ValueMap**. Wartości pobierane z innych źródeł danych, np. z usługi, pozostają bez zmian. Dlatego tablica zasilana również z innego źródła nie jest pusta po wyczyszczeniu. Więcej informacji o źródłach danych znajduje się na stronie [Edycja modelu danych](https://docs.eximee.com/budowanie-aplikacji/model-danych/edycja-modelu-danych.md#zrodlo-danych).

#### Wskazanie klucza

Klucz podaje się jako ścieżkę rozdzieloną kropkami, tak samo jak przy odczycie z modelu ([API modelu danych](https://docs.eximee.com/budowanie-aplikacji/model-danych/wykorzystanie-modelu-danych/api-modelu-danych.md)):

* Tablicę można wskazać z `[]` lub bez tego oznaczenia: `kredyt.zobowiazania` i `kredyt.zobowiazania[]` czyszczą całą tablicę. Rodzaj klucza wynika z definicji modelu danych.
* Tablicę nadrzędną wobec wskazanego klucza można oznaczyć przez `[]` lub indeks elementu: `kredyt.wnioskodawcy[].dochody` czyści dochody wszystkich wnioskodawców, a `kredyt.wnioskodawcy[1].dochody` - tylko dochody wnioskodawcy o indeksie 1 (drugiego na liście).
* Czyszczenie obejmuje wskazany węzeł i jego węzły podrzędne: `kredyt.wnioskodawca` nie czyści klucza `kredyt.wnioskodawcaDodatkowy`.
* Nie można wyczyścić pojedynczego elementu tablicy: `kredyt.zobowiazania[2]` nie powoduje wyczyszczenia żadnych wartości.

#### Kolejność zapisu

Metoda `complete` najpierw czyści wskazane klucze, a następnie zapisuje pozostałe wartości z tego samego wywołania. Dzięki temu w jednym wywołaniu można wyczyścić dotychczasowe wartości i zapisać nowe, np. zastąpić całą tablicę nowymi elementami:

```js
context.complete({}, {
    "kredyt.zobowiazania": null,
    "kredyt.zobowiazania[0].bank": "Bank A",
    "kredyt.zobowiazania[0].kwota": "500"
});
```

Po zakończeniu zadania tablica `kredyt.zobowiazania` zawiera jeden element z wartościami bank: `Bank A` / `500`.

{% hint style="warning" %}
Jeśli zadanie zakończy się metodą `handleFailure` lub `handleBpmnError` albo zostanie przerwane wyjątkiem przed wywołaniem `complete`, żadne wartości nie zostaną wyczyszczone ani zapisane.
{% endhint %}

#### Klucz, którego nie można wyczyścić

Wskazanie klucza, którego nie ma w definicji modelu danych, lub użycie niedozwolonej notacji nie powoduje wyczyszczenia żadnych wartości ani przerwania zadania. Niedozwolona notacja to np. `kredyt.zobowiazania[2]`, użycie `[]` przy polu, które nie jest tablicą, lub podanie nazwy zmiennej zamiast indeksu elementu.

#### Czego czyszczenie nie obejmuje

Czyszczenie jest dostępne wyłącznie przez metodę `complete` w zadaniu skryptowym. Opróżnienie pola w formularzu nie powoduje wyczyszczenia klucza - formularz zapisuje pusty tekst jako zwykłą wartość. Obiekt `api.model.v1` służy wyłącznie do odczytu.


---

# 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/zadanie-skryptowe-scripttask/api-zadan-skryptowych.md?ask=<question>&goal=<user_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.
