Scripts API

Downloading input data

Below is sample code that shows how to use input and how to return data.

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 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 the value "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 the value "defaultIfEmpty",

• Map<String, List<String>> getInputParameters(); - returns the entire map of input data that it stores,

• String isVisible(final String id); - retrieves information whether the component with the specified id is visible,

• String getValue(final String id); - retrieves the value of the component (also a session variable) with the specified id,

• void setValue(final String componentId, final String value); - sets the value value of the component with the specified componentId. The rule for providing componentId is the same as for getValue. When calling a script inside a composite component, to set the value of a component / session variable embedded in the same component, the componentId should be prefixed with the character @

WARNING! An attempt to perform setValue on a component that listens to another component or on a component to which other components listen 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 specified id

WARNING! The attributes that can be retrieved 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 a validator

Output from Service script

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

1. List of maps - the array of objects on the output is parsed into a list of maps, and then processed in the standard way.

2. Single map - the return is wrapped as a single-element list and then processed in the standard way.

Script output with an example list:

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

Logging

Input data logging is automatic

Manual logging should comply 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

It is possible to throw a business exception from a script. Sample code:

function callService(context) {
    const firstArgument = context.getFirstParameter('firstArgument');
    let builder =  context.getErrorPageDefinitionBuilder();
    builder.body('body');
    context.throwBusinessException(builder);
    return [{'firstOutput': firstArgument}];
}

Possible methods that can be invoked on the context object:

context.getErrorPageDefinitionBuilder() .body(string) .styleName(string) .msg(string) .pageTitle(string) .pageTitleKey(string) .sidebarSlot2TextContent(string) .sidebarSlot2(string) .sidebarSlot1TextContent(string) .sidebarSlot1(string) .retryButtonAvailable(string) .retryButtonAvailable(boolean) .logobarTitle(string) .logobarTitleKey(string) .logobarDescription(string) .bodyTextContent(string) .parameter(String key, String value) .cause(Throwable cause) .redirectUrl(string) .redirectDelayInMillis(string) .businessFormIdentifier(string)

Saving temporary data

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

Possible methods that can be called on the registry:

• save(namespace, id, data) - save data

• saveVersion(namespace, id, data, version) - save data with version verification. If the version field is unset or empty - save 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) - retrieve data

• getVersion(namespace, id) - retrieves the object { data: 'saved data', version: 'current data version' }

• delete(namespace, id) - delete data.

Data is stored in namespaces (namespace in the methods) set by administrators. Each namespace can have a configured data lifetime. By default it is 90 days. Providing the same id across several save calls updates the data associated with that id. The data version is a unique identifier generated with each data save.

The object requires a running EximeeRegistry application to function correctly.

Saving data using EximeeRegistry is not intended for permanent storage!

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 mismatch, save will fail
context.registry().delete('test','123123');

Retrieving the context of the logged-in user

Feature available from platform version: 2.3403.0

The feature works on requests launched in the webforms application with oauth authorization configured. However, it does not work on requests launched in the Eximee Dashboard application

It is possible to retrieve the context of the currently logged-in user who fills the request.

API

/**
 * The form security context, containing security-related data. After implementing this feature it will contain the identity of the current user.
 */
interface SecurityContext {
  /**
   * Identity of the current user
   */
  getCurrentUser(): Identity | null;
}
 
interface ScriptApi {
  // ...
  /**
   * Retrieve the current user context
   */
  getSecurityContext(): SecurityContext;
}
 
/**
 * Representation of a user role
 */
interface Role {
  name: string;
}
 
/**
 * Representation of user identity
 */
interface Identity {
  /**
   * Identifier of the user's identity. In the context of this topic always 'current'
   */
  id: string;
  /**
   * Username. In the context of this topic it is the employee's SKP.
   */
  username?: string;
  /**
   * User roles
   */                              
  roles?: Role[];
 
  /**
   * User's first name
   */
  firstName?: string;
 
  /**
   * User's last name
   */
  lastName?: string;
}

When running a script without a logged-in user context the method context.getSecurityContext() will return the value null

Example usage in a script of the user context

function callService(context) {
    context.getSecurityContext().getCurrentUser();               
  // return: { id: 'current', username: '100001', firstName: 'Jan', lastName: 'Kowalski', roles: [{name: 'role_001'}, {name: 'role_002'}] }
    // Checking whether the logged-in user has the role "role_001".
    var hasRole = context.getSecurityContext().getCurrentUser().roles.map(x=> x.name).includes("role_001");
     
    // Retrieving the username of the currently logged-in user. 
    var username = context.getSecurityContext().getCurrentUser().username;
}

Retrieving application configuration

Feature available from platform version: 3.190.0

The functionality works on requests launched as Business application

The application configuration retrieval functionality is available for scripts (scriptService), script tasks (scriptTask) and validation scripts (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;
        }
    }
}

Sample script 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

Requires the xlsx-sheet-handling-module

It is possible to read xlsx files attached to a request. For this purpose, use the xlsx-sheet-handling-module and the endpoint provided by it /xlsx/v1 - the module is currently delivered separately, appropriate access configuration to the service must be performed in ScriptApi. The request to the module should include:

{
    content: string
}

where in content we pass the file in base64 form. In this form it is passed to the service when we map an uploader to the input (in the case of multiple files in the uploader it is a list). In the response we will receive a map divided as: 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 Content of TextContent

Feature available from platform version: 3.332.0

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

const artifactName = "footer";
const artifactVersion = "*";
const lang = "pl";
 
const textArtifact = api.repository.v1.textContent(artifactName, artifactVersion);
const footerPl = textArtifact.language(lang).text();

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

2. the 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 = "footer";
const artifactVersion = "*";
const lang = "pl";
 
let textArtifact;
try {
    textArtifact = api.repository.v1.textContent(artifactName, artifactVersion);
} catch (error) {
    return [{'output': "No artifact found with name: " + artifactName + " and version: " + artifactVersion}]
}
 
let footerPl;   
try {
    footerPl = textArtifact.language(lang).text();  
} catch (error) {
    return [{'output': "No translation found in the artifact for language: " + lang}];
}
 
return [{'output': footerPl}];

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 Combobox (Value selection field) component

The script populates Value selection field from a list (Combobox) based on the provided 'locale' parameter.

Outputs id, label, and description should be connected to the appropriate combobox fields, respectively id, text, and description.

Script populating the combobox:

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': 'Default translation value 1', 'description': 'Description 1', },
            { 'id': 2, 'label': 'Default translation value 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 specified id. For the Attachments component the names of added files are specified by the attribute fileNames and arrive 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.

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

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

Retrieving the value of a Combobox from a repeatable section

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

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