Custom JavaScript execution

Overview

This documentation provides detailed guidelines on utilizing the JavaScript execution feature within our application. This capability enhances the flexibility and functionality by enabling users to define and execute custom scripts that can interact dynamically with various application elements. Integrated through an internal API, these scripts provide a robust method for automation and customization of processes and data handling.

Key Features

The JavaScript execution is designed for integration with "concept types" through two specific script functionalities:

Guard Scripts: These scripts act as safeguards for updates to the concepts. They are saved as part of the concept type. They evaluate conditions and determine whether an update should proceed or be rejected.
Calculated Fields Scripts: These scripts perform operations such as calculations, concatenations, and other manipulations. The results can then be displayed in the concept.

API Capabilities

The internal JavaScript API exposes several objects and functionalities to the executing scripts, enabling them to interact deeply with the system's internal structures. This interaction includes access to persisted concepts in the current context, master data, the current user, and, in specific cases, the potential future state of a concept (for Guard Scripts) or the fields dependent on calculations (for Calculated Fields Scripts).

Logging Functionality

Scripts executed within the application have the capability to log messages to the application log, which can be invaluable for debugging and monitoring script execution. This logging is facilitated through the SLF4J logging facade, providing a standardized way to log messages at various levels (e.g., info, debug, error).

Using the Logger

To log messages, scripts first need to obtain a logger instance from the execution context. This instance can then be used to log messages at the desired level. Below is an example of how to obtain a logger and log an informational message:

let log = context.getLogger(); 
log.info("Guard currently executing");

Accessing Master Data

Scripts have the capability to access and utilize master data, which are tables of fixed data independent of the concept units. Master data provides a stable dataset that scripts can rely on for performing various operations, such as validations and computations.

Example how to Access Master Data

To access master data within a script, the script can retrieve a master data table using the execution context provided by the internal JavaScript API. Here is an example of how to access and log information from master data in a guard script:

let log = context.getLogger();
let masterDataTable = context.getMasterDataTable("masterDataKey");
log.info("Master data table title: " + masterDataTable.title());
let masterDataRow = masterDataTable.rows()[0];
log.info("Master data row title: " + masterDataRow.title());
log.info("Master data row cell 1 value: " + masterDataRow.cells()[0].value());
log.info("Master data row cell 2 value: " + masterDataRow.cells()[1].value());

In this example, the script retrieves a master data table using a key, and then accesses data from the first row of the table. This data can be used to perform checks, inform calculations, or influence script behavior based on the stable data provided.

This ability to interact with master data ensures that your scripts can operate with a consistent set of data, crucial for maintaining the integrity and reliability of operations within the application.

Available methods to Access Master Data

Below is a description of the methods available on the MasterDataTable object. This object encapsulates the structure and data of a master data table, which includes its columns and rows.

Method	Return Type	Description
`id()`	`String`	Retrieves the unique identifier of the master data table.
`key()`	`String`	Retrieves the key associated with the master data table.
`title()`	`String`	Retrieves the title of the master data table.
`columns()`	`List<MasterDataColumn>`	Retrieves a list of columns within the table.
`rows()`	`List<MasterDataRow>`	Retrieves a list of rows within the table.
`created()`	`ChangeContextDto`	Retrieves the creation context of the table.
`modified()`	`ChangeContextDto`	Retrieves the last modified context of the table.

Below is a table describing the methods available on the MasterDataColumn object, which represents a column within a master data table.

Method	Return Type	Description
`key()`	`String`	Retrieves the unique key identifier of the column.
`title()`	`String`	Retrieves the title or name of the column.
`valueType()`	`PropertyDataType`	Retrieves the data type of the column's values.

Here's a table that outlines the methods accessible on the MasterDataRow object, which encapsulates a row within a master data table.

Method	Return Type	Description
`id()`	`String`	Retrieves the unique identifier of the row.
`key()`	`String`	Retrieves the key associated with the row.
`title()`	`String`	Retrieves the title of the row.
`cells()`	`List<MasterDataCell>`	Retrieves a list of cells contained in the row.
`created()`	`ChangeContext`	Retrieves the creation context of the row.
`modified()`	`ChangeContext`	Retrieves the last modified context of the row.

Lastly, the following table describes the methods on the MasterDataCell object, which represents individual cells within a master data row.

Method	Return Type	Description
`key()`	`String`	Retrieves the key identifying this cell in the row.
`value()`	`String`	Retrieves the value held by this cell.