Data Shop Script Examples

The following chapter shows examples of how to implement common use cases for Data Shop scripts.

For more information about the Data Shop itself, see Data shop.

Most scripts use the MetaMap to access metadata of the current context. For more information, see MetaMap.

Filtering Option Lists in Data Shop Scripts

This example shows how to use a Data Shop init script to enable or disable specific entries of an option list for a form parameter. The script evaluates each option and decides whether it should be selectable for the user.

This is useful when only a subset of predefined environments or choices should be available based on your own rules.

Data Shop scripts can set values for form parameters, enable or disable fields, hide fields, or control the list of options that will be displayed in a drop-down box.

The example assumes the following:

There is a form parameter Source Environment mapped to a custom parameter, using a list of possible values.
The form parameter is configured with multiple possible values, for example:
Production HR Environment
Production Environment
The script is configured as a revalidation script on the data shop.

During revalidation, the script:

iterates over all options of the Source Environment form parameter,
enables the option whose displayName is Production HR Environment,
disables the option whose displayName is Production Environment.

All other options remain unchanged. You can extend this pattern to implement more complex rules, for example depending on other form parameter values or on the current user.

for (entry in meta['sourceEnv'].options) {
    entry.enabled = false

    if (entry.displayName == 'Production HR Environment') {
        entry.enabled = true
    }
}

Using Init Script to Pre-select Source Environment

This example shows how to use a Data Shop init script to pre-select a default value for the Source Environment parameter. The script sets the first enabled option in the Source Environment drop-down list as the initial value when the order form is opened.

The script is executed in the initialization phase of a Data Shop order. It has access to:

meta – metadata of the form parameters, including available options.
dataShop – the Data Shop object that stores the current parameter values of the order.
environmentList – a list of available environment objects that can be assigned to the Source Environment parameter.

The user that runs the Data Shop execution must have READ permission on the environment list and on the individual environments. Otherwise, the script cannot access the environments via the API and will fail to set the default value.

def environmentList = api.environments

for (entry in meta['sourceEnv'].options) {
    if (entry.enabled && dataShop.sourceEnv == null) {
        dataShop.sourceEnv = environmentList.find { it.displayName == entry.displayName }
    }
}

Checking User Permissions in Data Shop Scripts

Data Shop scripts can evaluate the current user’s roles and use this information to control the order form. This allows you to expose sensitive options only to users with extended permissions, while hiding or restricting them for regular users.

Typical examples are:

showing additional expert options only to admins,
hiding advanced filters from regular requesters,
enabling or disabling certain choices depending on the user’s role.

This example assumes the following:

The script is configured as an init order script or revalidation script on the data shop.
The current user is available as user and provides a collection of authorities (roles) in user.authorities.
There is at least one form parameter that should only be available for users with an authority that contains the string EXTENDED.
This form parameter is mapped to a custom parameter on the executed task template or workflow template.

By checking the user’s authorities, your script can:

hide sensitive form parameters for non‑privileged users by setting meta['parameterName'].visible = false,
disable fields by setting meta['parameterName'].enabled = false,
prefill or override values of form parameters (for example, set a specific default value for admins),
restrict available options in lists (for example, remove or disable certain entries for regular users).

The script performs the following actions:

It checks whether the current user has at least one authority that contains the substring EXTENDED.
It uses the variable isExtended to store the boolean information if the user has the role or not.
It then uses this flag to decide how to configure a specific form parameter. In the example below, the parameter is hidden completely for non‑extended users.

/**
 * Check whether the current user has any authority that contains 'EXTENDED'.
 * If not, hide a sensitive form parameter in the Data Shop form.
 */

// Check if the current user has any authority containing 'EXTENDED'
def isExtended = user.authorities.any { authority ->
    authority.toString().contains('EXTENDED')
}

// Hide the sensitive form parameter for non-extended users
if (!isExtended) {
    meta['customParameter'].visible = false
}

You can extend the same pattern for more complex scenarios, such as disabling options, changing defaults, or showing additional parameters for specific roles.

Validating Order Size and Time Window in a Validation Script

This example shows how to use a Data Shop validation script to enforce business rules before an order is placed. It combines two checks:

It limits how many employee numbers can be entered in a single request.
It ensures that large orders are only executed outside of business hours by adjusting the Start at time and rejecting the order with a clear error message.

In this example, the form parameter emp_no* is mapped to a custom parameter emp_no on the data shop and contains a comma-separated list of employee numbers, for example 10001,10002,10003.

import java.time.LocalDateTime

def limit = 3

// Only allow more than 3 employee numbers outside of business hours
if (dataShop.emp_no.split(',').size() > limit) {

    // Determine the effective execution time: either now or the scheduled startAt
    def exTime = LocalDateTime.now()
    if (startAt) {
        exTime = startAt
    }

    // Allowed time window for normal orders: 06:00 to 18:00
    def minTimeValue = 6
    def maxTimeValue = 18
    def minTime = LocalDateTime.of(exTime.year, exTime.month, exTime.dayOfMonth, minTimeValue, 0)
    def maxTime = LocalDateTime.of(exTime.year, exTime.month, exTime.dayOfMonth, maxTimeValue, 0)

    // If a large order is requested during business hours, move it to 18:00 and reject it
    if (minTime.isBefore(exTime) && exTime.isBefore(maxTime)) {
        // Move execution to the next allowed time within the configured window
        startAt = maxTime

        // Reject the order with a clear validation error
        throw new ScriptValidationException(
            "Orders with more than ${limit} employee numbers " +
            "are only allowed to run between ${maxTimeValue}:00 and ${minTimeValue}:00."
        )
    }
}

It is also possible to schedule the execution outside business hours automatically instead of rejecting the order. This can be done by changing the startAt time. In the example below, the order is rejected so that the user has the option to adjust the order and try again.

Preselecting and locking a Collection Form Parameter

This example shows how to use a Data Shop init script to:

ensure that a specific default value is present in a collection‑type form parameter, and
disable this value in the option list so that the user can see it but cannot change it.

This is useful when a parameter must always contain at least one fixed value (for example CUSTOMER), while the user may still add additional values.

The example assumes the following configuration:

There is a collection‑type form parameter mapped to a custom parameter named components. The Components form parameter is a multi‑select control in the Data Shop order form.

Script Logic

During initialization, the script:

initializes dataShop.components as an empty collection if it is not yet set, checks whether the collection already contains the required value CUSTOMER, appends CUSTOMER to the collection if it is missing, and iterates over all options in meta['components'].options and disables the option whose value is CUSTOMER, so the user cannot change its value.

// Initialize the collection if it is not set yet
dataShop.components = dataShop.components ?: []

// Add the required default value if it is missing
if (!dataShop.components.contains('CUSTOMER')) {
    dataShop.components += 'CUSTOMER'
}

// Disable the corresponding option
for (entry in meta['components'].options) {
    if (entry.value == 'CUSTOMER') {
        entry.enabled = false
    }
}