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:

1. 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.

2. 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 Concept Data

Scripts can access concept data in two forms: the version persisted in the database and, in the case of Guard Scripts, the prospective version that includes pending changes. These versions are accessed through the execution context provided by the internal JavaScript API.

Access Methods

• Persisted Concept: Represents the concept as it is currently stored in the database. Accessed with:

  let persistedConcept = context.getPersistedConcept();

• Current Concept (Guard Scripts only): Represents the concept with pending changes that will be saved if the guard script allows it. Accessed with:

  let currentConcept = context.getCurrentConcept();

Example Script

The following example script demonstrates how a Guard Script might use these methods to check if the title of a concept has been changed and, if so, logs the change and decides whether to allow the update:

let log = context.getLogger();
let persistedConcept = context.getPersistedConcept();
let currentConcept = context.getCurrentConcept();

let persistedTitle = persistedConcept.getTitle();
let currentTitle = currentConcept.getTitle();

log.info("Checking title change for approval...");
if (currentTitle !== persistedTitle) {
    log.info("Title change detected: from '" + persistedTitle + "' to '" + currentTitle + "'.");
    // Additional conditions can be checked here
    return true;  // Allow the update
} else {
    log.info("No title change detected.");
    return false; // Prevent the update if no changes are made to the title
}

In this script, the getTitle() method is used to retrieve the title from both the persisted and current concept instances, allowing the script to compare them and decide based on business rules whether to allow the update.

Concept Object Methods

The Concept object provides several methods that enable scripts to interact with concept data effectively. These methods are available across all types of concepts within the application, ensuring a consistent interface for script developers.

Available Methods

Below is a list of methods that scripts can access to retrieve and manipulate data from any concept (configuration area, unit, configuration and configuration item):

Accessing Properties and Complex Properties

The Concept object offers methods to retrieve simple properties and complex properties (also known as records) in various data types.

Simple Property Access Methods

These methods allow you to retrieve simple properties directly from a concept in different data types. The methods that return the property as their type throw an exception if the property doesn’t actually have this type:

Complex Property (Record) Access Methods

Complex properties are accessed via the getComplexProperty(String recordTypeKey) method, which retrieves a list of ComplexProperty objects. Each ComplexProperty can hold multiple properties of various types.

Methods Available in ComplexProperty

ConceptType Object Methods

The Concept object also includes access to its associated concept type through the ConceptType, which carries detailed type-specific information. This is crucial for scripts that need to adapt their behavior based on the type of the concept they are interacting with.

Available Methods

Below is a list of methods provided by the ConceptType object, accessible through the Concept object:

Type-Specific Concept Methods

Depending on the type of concept instance, additional methods are available that facilitate accessing related concepts and properties specific to their functional role within the application. Below is a breakdown of these methods by concept type:

Unit (Component)

For concepts that are instances of "Unit" or known as "Component":

Configuration

For concepts that are instances of "Configuration":

Configuration Item

For concepts that are instances of "Configuration Item":

StorageLocation Methods

The StorageLocation object provides specific information about where the configuration item is stored:

Accessing Calculation-Dependent Fields

In Calculated Fields Scripts, the getCalculationDependentFields() method provides access to specific fields that are pertinent to the calculations being performed. This method returns an object that returns properties and complex properties (records) in the same format as the Concept object.

Methods Available

This object provides similar methods to those available in the Concept object for accessing properties and records (see here):

• Property Access Methods: Includes methods to retrieve simple properties in various data types (e.g., getProperty(String key), getPropertyAsInt(String key), etc.).

• Complex Property (Record) Access Methods: Includes methods to access complex properties or records such as getComplexProperty(String recordTypeKey) which retrieves a list of complex properties (records) based on the record type key.

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.

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

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

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

Accessing Current User Details

Access via:

let user = context.getUser();
log.info("User name: " + user.username());

The getUser() method provided by the script context allows access to the current user's information, encapsulated within a User object. This functionality is essential for retrieving user-specific data, which can influence script logic or user experience enhancements.

User Access Methods

The User object represents detailed user information. Here is a breakdown of the methods you can use to access this data directly: