Page Comparison

...

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

Expected Return Values for Guard Scripts

Guard Scripts are used to determine whether updates to a concept should proceed or be blocked. The outcome of these scripts can be communicated back to the application in two forms:

1. Boolean Return Values

• True: Indicates that the guard script has approved the update, allowing it to proceed.

• False: Indicates that the guard script has blocked the update. If the return value is false, a generic message will be displayed to the user in the UI, such as "Update not allowed by system rules."

2. GuardResult Object

For more nuanced control over the feedback provided to users, scripts can return a GuardResult object, which allows for customized messages and detailed feedback about why an update was blocked or allowed.

Structure of the GuardResult Object

AffectedProperty Record

Example Use Cases

• Success = True: The update is allowed to proceed, and no details are shown to the user since the operation complies with all rules.

• Success = False: The update is blocked. The details specified in the GuardResult object, such as title, reason, and information about affectedProperties, will be displayed in the UI to inform the user precisely why the update was not permitted.

Implementing Guard Scripts with GuardResult

Guard Scripts can use these structures to provide clear and actionable feedback to users, especially when rejecting an update. For example:

let someCondition = false; // Assume some condition that needs to be checked
let anotherCondition = true; // Another condition for demonstration

if (!someCondition || !anotherCondition) {
    return {
        success: false,
        title: "Update Rejected",
        reason: "Multiple conditions for the update are not met.",
        affectedProperties: [
            {
                reason: "First required condition is not met",
                propertyIdentifier: "firstPropertyKey"
            },
            {
                reason: "Second required condition is not met",
                propertyIdentifier: "secondPropertyKey"
            }
        ]
    };
}
return true; // If all conditions are met, allow the update

Expected Return for Calculated Fields Scripts

Calculated Fields Scripts must return a specific object format to integrate smoothly with the rest of the application, ensuring that calculated data is displayed correctly in the UI. This object, CalculatedFieldResult, contains a list of CalculatedField objects that represent individual calculated field values.

Structure of Return Object

Here is the expected structure for the return object in Calculated Fields Scripts:

• CalculatedFieldResult:

  • Contains a list of CalculatedField objects.

• CalculatedFieldDto:

  • id: The user-defined identifier (or key) for the calculated field.

  • value: The calculated value as a string.

Example Script for Returning Calculated Fields

Here is an illustrative example of how a Calculated Fields Script might construct and return the expected result:

// Example calculated values
let result2Value = "42"; // Some dynamic calculation result
let concatenatedKeyValue = "Hello, World"; // Another calculation result

return {
    calculatedFields: [
        {
            id: "result2",
            value: result2Value
        },
        {
            id: "concatenatedKey",
            value: concatenatedKeyValue
        }
    ]
};

Example Use of Calculated Fields in UI Masks

When calculated fields are added to a concept type, the user can set up a display mask that utilizes these identifiers to format and show the calculated values dynamically. For instance, consider the following example mask:

Value Of Calculated Field 2: {result2} Concetenated result: {concatenatedKey}

In this mask:

• result2 and concatenatedKey are identifiers used in the calculated fields result.

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

...