Script tasks API

The platform provides the ability to create script task handler logic from Eximee Designer. The process designer only needs to write the handler logic and attach it in the process.

Creating a script task

We can create and edit script tasks using the Eximee Designer application. To do this, in the Library select the tab Script tasks:

Illustration 1. Script tasks tab window

A detailed description of creating scripts is available in: Script tasks.

Handler API

interface Task {
   getVariable(name): string;                                 // Getting a process variable with the identifier specified in the parameter
   getAllVariables(): {[key: string]: string};                // Getting all variables in the process
   getProcessIntanceId(): string;                             // Returns the process instance identifier
}
 
interface Context {
   complete(variables: [key: string]: string, modelChanges?: [key: string]: string): void; // Completing the task and passing to the process the variables indicated in the parameter and optionally changes in the data model
   handleFailure(cause: string): void;                        // Reporting an incident on the task (e.g., system error) together with specifying the reason indicated in the parameter (the process stops until intervention)    
   handleBpmnError(errorCode: string, cause?: string): void;  // Reporting a defined business error on the task along with the error code and the reason indicated in the parameter (the BPMN error handling path is triggered)
    
   // Deprected
   getModel(String processInstanceId, List<String> fieldsNames): Map<String, String> // Calling the data model by providing the process instance id and the list of keys whose values we want to retrieve.
                                                                                     // Deprecated method. Use api.model instead
}
 
interface Logger {
    info(message: string, ...args: any);                      // Logging at INFO level                
    debug(message: string, ...args: any);                     // Logging at DEBUG level
    warn(message: string, ...args: any);                      // Logging at WARN level
    error(message: string, ...args: any);                     // Logging at ERROR level
    trace(message: string, ...args: any);                     // Logging at TRACE level
}
 
function nonsensitive(arg: any): String;
 
function handle(task: Task, context: Context): void {}

Setting the list of groups that will have access to the process instance on the cases list

Operations and access to process data

Example script tasks

The script retrieves the variable with identifier "testVariable", multiplies it by itself, and assigns the result to a new variable "result":

function handle(task, context) {
    Logger.info("Starting script task sensitiveName={}, nonSensitiveName={}", 'SECRET_DATA', nonsensitive('NONSECRET_DATA'))
 
    const testVariableNumber = task.getVariable('testVariable');
    const testVariablePower = testVariableNumber * testVariableNumber;
     
    Logger.info("Finishing script task")
    context.complete({'result': testVariablePower});
 }

Calling REST services in a script task

Call documentation: [Rest] Calling external REST services (ScriptCode)

The only change compared to the above documentation is the configuration file.

The one for the ScriptCode Handler is called script-handler-api.xml and is located in the directory /etc/eximee/webforms/script-handler-config

Example of a script task calling an external REST service:

function handle(task, context) {
    // Retrieving the process variable with the key "testVariable"
    const value = task.getVariable('testVariable');
     
    // Retrieving the process variable with the key "result"
    const result = task.getVariable('result');
 
    if (value == null || isNaN(value)) {
        // Reporting an error on the task with error code "errorCode"
         context.handleBpmnError("errorCode", "No value for the process variable with key 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);
    }      
}

Retrieving business application configuration

Call documentation: Scripts (scriptService)#Retrievingapplicationconfiguration

Example of a script task that retrieves configuration:

function handle(task, context) {
    // Retrieving variables from configuration
    const skipTask = api.config.v1.get("script.task.skip.task")
    const titleName = api.config.v1.getOrDefault("script.task.title.name", "Default title")
     
    // Completing the task and passing variables (skipTask, titleName) to the process
    context.complete({'skipTask': skipTask, 'titleName': titleName});
}

Calling Eximee Status in the ScriptCode Handler

For the call to work correctly you must fill the EXIMEE_STATUS_URL parameter pointing to the eximee-status API.

Methods invoking eximee-status require a process variable statusId, which should contain the application number for which the specified update should occur.

Status API

interface EximeeStatusClient {
   updateStatus(statusName: string, statusDescription: string): void;   // Updating the name and description of the status
   updateMetadata(metadata: string): void;                               // Updating application metadata
   getMetadata(): Object;                                               // Retrieving application metadata
   getClientFormsBasicInfo(): Object;                                   // Retrieving the list of application statuses for the logged-in client (Method available from version 4.154.0. The client must be logged in for the functionality to work.)
 }

Example ScriptCodeHandler calling 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);
    }      
}

Retrieving Content content

Functionality available from platform version: 3.332.0

From a script task you can retrieve the content of an artifact Content (textContent) created in Eximee Designer, using the function: api.repository.v1.textContent. This function returns an object that has contents for each of the defined translations. To get the content for a given translation we use the function language. Example usage:

const artifactName = "stopka";
const artifactVersion = "*";
const language = "pl";
  
const artifactContent = api.repository.v1.textContent(artifactName, artifactVersion);
const footerPl = artifactContent.language(language).text();

1. The function textContent throws an exception if it does not find an artifact with the given parameters.

2. The function language throws an exception if it does not find a translation in the given language.

If we are not sure that the parameters we provided are correct, we can handle exceptions using try catch:

const artifactName = "stopka";
const artifactVersion = "*";
const language = "pl";
  
let artifactContent;
try {
    artifactContent = api.repository.v1.textContent(artifactName, artifactVersion);
} catch (error) {
    context.handleFailure("No artifact found with name: " + artifactName + " and version: " + artifactVersion);
    return;
}
  
let footerPl;  
try {
    footerPl = artifactContent.language(language).text(); 
} catch (error) {
    context.handleFailure("No translation was found in the artifact for language: " + language);
    return;
}
 
context.complete({'output': footerPl});

Data model

More information in Data model API

Saving data in the data model

In script tasks we can save data to the model using the 'complete' method; the first parameter saves data to the process, and the second parameter saves data to the model:

The model key must exist in the data model for it to be saved correctly

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