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

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:

Ilustracja 1. Okno zakładki zadań skryptowych

Szczegółowy opis tworzenia skryptów dostępny jest w: Zadania skryptowe.

API handlerów

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
   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 {}

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

Przykładowe zadania skryptowe

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

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

Dokumentacja wywołania: [Rest] Wołanie zewnętrznych usług RESTowych (ScriptCode)

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

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

function handle(task, context) {
    // Pobranie zmiennej procesowej o kluczu "testVariable"
    const value = task.getVariable('testVariable');
     
    // Pobranie zmiennej procesowej o kluczu "result"
    const 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

Dokumentacja wywołania: Skrypty (scriptService)#Pobieraniekonfiguracjiaplikacji

Przykład zadania skryptowego z pobraniem konfiguracji:

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

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.

Status API

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:

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

Funkcjonalność dostępna od wersji platformy: 3.332.0

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:

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

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.

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:

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

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:

Klucz modelu musi istnieć w modelu danych żeby poprawnie zostało zapisane

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);
}