Scripts API

Retrieving input data

Below is an example code that shows how to use input and how data should be returned.

function callService(context){
  const firstArgument = context.getFirstParameter("firstArgument");
  const firstArgumentList = context.getParameters("firstArgument");
  const keySet = context.getInputParameters().keySet();
  const comboboxLabel = context.getData("GesCombobox1","label");
  const result = "service script constant " + firstArgument + " list value: " + firstArgumentList + " and first from list: " + firstArgumentList.get(0) + " keySet " + keySet;
  return [{'output': result}];
}

Input to the Service Script

As input (parameter context in the code above) there is an object that provides the following methods:

• List<String> getParameters(final String name); - retrieves a specific list from the input data map,
• String getFirstParameter(final String name); - retrieves the first element from a specific list in the input data map or returns "null",
• String getFirstParameter(final String name, final String defaultIfEmpty); - retrieves the first element from a specific list in the input data map, and if it does not exist or is empty returns "defaultIfEmpty",
• Map<String, List<String>> getInputParameters(); - returns the entire input data map that it stores,
• String isVisible(final String id); - retrieves information whether the component with the given id is visible,
• String getValue(final String id); - retrieves the value of the component (also a session variable) with the given id,
• void setValue(final String componentId, final String value); - sets the value value of the component with the given componentId. The rule for specifying componentId is the same as with getValue. When calling a script inside a composite component, in order to set the value of a component / session variable embedded in the same component, you should prefix componentId with the character @

NOTE! An attempt to execute setValue on a component that listens to another component or on a component, that which is listened to by other components, will result in throwing an exception.

• String getData(final String id, final String attribute); - retrieves the value of a specific attribute for the component with the given id

NOTE! The available attributes depend on the component.

• List<Map<String, String>> callService(String name, Map<String, List<String>> input); - allows calling ServiceProxy,
• ValidatorOutput validate(String name, Map<String, List<String>> input); - allows calling the validator

Output from the Service Script

We can return the result of script execution in two ways:

1. List of maps - the array of objects in the output is parsed into a list of maps, then processed in the standard way.
2. Single map - the return value is wrapped as a single-element list, then processed in the standard way.

Script output with an example list:

  return [{'output': 'result1'},{'output': 'result2'},{'output': 'result3'}];

Logging

Logging input data is automatic

Manual logging should be consistent with the description in Logging in ScriptCode

function callService(context) {
    const sessionVariable = context.getValue("@sessionVar");
    Logger.info('Session variable value [arg1={}, arg2={}]', nonsensitive('arg1 nonsensitive test'), sessionVariable);
    return [{'sessionVar':sessionVariable }];
}

Throwing business exceptions

Business errors are described in detail on the page Error pages.

Saving temporary data

Outdated! The following fragment about the Eximee Registry API requires updating.

It is possible to save certain data between service calls. The object is used for this registry.

Possible methods that can be called on the object registry:

• save(namespace, id, data) - saves data
• saveVersion(namespace, id, data, version) - saves data with version verification. If the version field is not set or is empty - saves without verification. If the value of the version field does not match the current version of the stored data, the request will end with an error.
• get(namespace, id) - retrieves data
• getVersion(namespace, id) - retrieves the object { data: 'saved data', version: 'current data version' }
• delete(namespace, id) - deletes data.

Data is stored in namespaces (namespace in the methods) defined by administrators. A data lifetime can be set for each namespace. By default, it is 90 days. Providing the same id across multiple save calls updates the data associated with that id. The data version is a unique identifier generated each time data is saved.

For correct operation, the object requires a running EximeeRegistry application.

Saving data using EximeeRegistry is not intended for storing anything permanently!

Examples:

context.registry().save('test', '123123', 'temporary data');
context.registry().get('test', '123123'); // will return 'temporary data'
const item = context.registry().getVersion('test', '123123'); // will return object {data,version}
context.registry().saveVersion('test','123123', 'new data', item.version); // version matches, save will succeed
context.registry().saveVersion('test','123123', 'new data', 'some other version'); // version does not match, save will fail
context.registry().delete('test','123123');

Retrieving application configuration

Functionality available from platform version: 3.190.0

The functionality works on requests run as Business application

The application configuration retrieval functionality is available for scripts (scriptService), script tasks (scriptTask), and script validators (validationScript).

In scripts, it is possible to retrieve the application configuration

interface Api {
    config: {
        v1: {
          get(key: string): string;
          getOrDefault(key: string, defaultValue: string): string;
        }
    }
}

Example script for retrieving configuration:

function callService(context) {
    let value1
    try {
        value1 = api.config.v1.get("application.url");
    } catch (e) {
        value1 = "default"
    }
 
    let value2 = api.config.v1.get("application.url");
 
    let value3 = api.config.v1.getOrDefault("not_existing_key", "defaultValue")
 
    return [{'value1': value1, 'value2': value2, 'value3': value3}];
}

Processing xlsx files

Required module xlsx-sheet-handling-module

It is possible to read xlsx files attached to the request. To do this, use the xlsx-sheet-handling-module and its provided endpoint /xlsx/v1 - the module is currently provided separately; the appropriate access configuration for the service in ScriptApi must be set up. The following request should be sent to the module:

{
    content: string
}

where in content we pass the file in base64 format. In this form it is passed to the service when we map uploader to the input (in the case of multiple files in uploader, it is a list). In response we will receive a map divided into: sheet → row → column

{
    "sheet": {
        "1": {
            "A": { "test"
                }
            }
    }
}

Example:

function callService(context) {
    let files = context.getParameters("uploader");
 
    if (files.size() === 0) {
        return [{}];
    }
 
    let header = {};
    let body = {'content': files.get(0)}
 
    try {
        let response = api.rest.v1.post('excelDocument', { pathParams: ['xlsx', 'v1'] }, header , body);
     
        return [{'output': JSON.stringify(response.body)}];
    } catch (error) {
        Logger.info(error );
        return [{'output': 'An error occurred'}];
    }
 
}

Retrieving the content of Content

Functionality available from platform version: 3.332.0

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

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

1. function textContent throws an exception if it does not find an artifact with the given parameters
2. 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 nazwaArtefaktu = "stopka";
const wersjaArtefaktu = "*";
const jezyk = "pl";
 
let artefaktTresci;
try {
    artefaktTresci = api.repository.v1.textContent(nazwaArtefaktu, wersjaArtefaktu);
} catch (error) {
    return [{'output': "No artifact found with name: " + nazwaArtefaktu + " and version: " + wersjaArtefaktu}]
}
 
let stopkaPl;   
try {
    stopkaPl = artefaktTresci.language(jezyk).text();  
} catch (error) {
    return [{'output': "No translation for language: " + jezyk + " was found in the artifact"}];
}
 
return [{'output': stopkaPl}];

Mathematical operations in ScriptCode

More information in Mathematical operations in ScriptCode

Operations and access to process data

More information in Operations and access to process data

Retrieving request statuses

More information in Retrieving request statuses

Data model

More information in Data model API

Other examples

Populating the List value selection component (Combobox)

The script populates Selection field from a list (Combobox) based on the passed 'locale' parameter.

Outputs id, label, and description should be bound to the corresponding combobox fields, respectively id, text, and description.

Combobox-populating script:

function callService(context) {
    const locale = context.getFirstParameter('locale');
    if (locale === 'pl') {
        return [
            { 'id': 1, 'label': 'Value 1', 'description': 'Description 1', },
            { 'id': 2, 'label': 'Value 2', 'description': 'Description 2' }
        ];
    } else if (locale === 'en') {
        return [
            { 'id': 1, 'label': 'Label 1', 'description': 'Description 1', },
            { 'id': 2, 'label': 'Label 2', 'description': 'Description 2' }
        ];
    } else {
        return [
            { 'id': 1, 'label': 'Value of default translation 1', 'description': 'Description 1', },
            { 'id': 2, 'label': 'Value of default translation 2', 'description': 'Description 2' }
        ];
    }
}

Retrieving file names from the Attachments component

The script uses the method getData(), which retrieves the value of a specific attribute for the component with the given id. For the Attachments the names of added files are determined using the attribute fileNames and come from the request as a string in JSON format (e.g. ["name1.png", "name2.png"]), therefore it is necessary to convert this string into an object using the method JSON.parse.

NOTE! The method getData() uses the component id, so the script is not universal - for each request, you must provide the appropriate component id Attachments:

function callService(context) {
    const zalacznik1 = JSON.parse(context.getData("@GesUploadFile1", "fileNames"));
    const zalacznik2 = JSON.parse(context.getData("@GesUploadFile2", "fileNames"));
}

Retrieving the value of the List value selection field (Combobox) from a repeatable section

The script uses the method getData(), which retrieves the value of a specific attribute for the component with the given id. For the List value selection field the values (labels) of the given keys are determined using the attribute label.

for (let i=0; i<10; i++)  {
        let id = "GesRepeatableSection1.row" + i + ".GesCombobox1";
        let etykieta = context.getData(id, "label");
}