Parameters and Custom Parameters

Working with Parameters and Custom Parameters

What is a Parameter in XDM?

In XDM, parameters can be used to control scripts and objects like workflows, task stage hooks or modification methods. They can also be used to store additional information or settings in objects which these do not store natively and which can be used later to control for example a script.

Each parameter has at least:

  • a name : the identifier used to refer to the parameter

  • a value : the concrete content used at runtime (for example a date, an ID, or a connection)

XDM uses several kinds of parameters:

  • System parameters

    Built‑in parameters provided by XDM. Typical examples are internal IDs, timestamps, user information, or automatically generated names. System parameters cannot be edited by users. They are created and maintained by XDM.

  • Object properties and parameters

    Parameters that belong to a specific XDM object, for example a task, workflow, environment, or data shop. They are visible as properties of that object and control how the object behaves. Examples:

    • a task template option that controls whether indexes are rebuilt

    • a data shop property that specifies which task or workflow template will be executed

  • Custom Parameters

    User-defined parameters that are defined once with a specific data type and possible values and can then be used on different objects to store specific values. Custom parameters can hold different types of values, for example:

    • simple types: Strings, Numbers, Boolean, Dates or Timestamps

    • references to XDM objects: environments, connections or collections

    • references to files managed in XDM

Custom Parameter Types

This section lists the available custom parameter types and gives a short description for each type.

Type Description

String

String parameters are free-text values such as names, IDs or codes.

Number

Number parameters are used for counts, limits, or numeric thresholds.

Boolean

Boolean parameters switch their value between true and false.

Environment

Environment parameters reference XDM Environment objects and are typically used to select source and target environments.

Connection

Connection parameters reference XDM Connection objects and are useful when different technical connections are possible.

Collection

Collection parameters reference XDM Collection objects and are typically used to select predefined sets of objects or configurations.

File

File parameters reference XDM file objects (for example libraries or configuration snippets).

Using Custom Parameters across Multiple Objects

Custom parameters in XDM are always properties of a specific object. They are stored on that object, and they are not automatically shared or forwarded to other objects. This means:

  • A custom parameter defined on two different objects represents two independent values.

  • Only the definition (name, type, allowed values, default) can be identical; the actual value is stored separately per object.

For example, you can define a custom parameter activateDataRelations of type Boolean:

  • On an application model, you set activateDataRelations = true to document that data relation rules should normally be active for this model.

  • On a specific environment, you set activateDataRelations = false because this environment is used only for technical checks where relations are not needed.

Although both objects use the same parameter name and type, each object keeps its own value. Changing the value on the application model does not change the value on the environment, and vice versa.

Custom parameters can be used like any other property of an object. In scripts or rules that receive the object in their context, you can read and use the parameter value from that object.

Automatic Parameter Inheritance between Templates and Executions

In some cases, XDM automatically propagates parameter values between related objects.

Task Templates and Tasks

Custom parameters that are defined on a task template are inherited by tasks created from that template. The task initially receives the same parameter definition and value as the template. The value can then be overridden on the task if needed.

Workflow Templates and Workflows

The same principle applies to workflows. Custom parameters defined on a workflow template are inherited by workflows that are based on this template and can be overridden there.

Modification Sets and Tasks

Custom parameters can be defined on a modification set and used in its modification rules. If the same custom parameter is also defined on the task template or on the task that uses this modification set, the value from the task template or task overrides the value from the modification set at execution time. This enables controlling the behavior of a modification set per task by configuring appropriate custom parameter values on the task template or task.

Value Forwarding between Tasks and Environments

If a custom parameter is added to an environment and also to a task template so that both objects have an identical parameter, then XDM will forward the value of that parameter from the task to the environment at runtime.

  • During task execution, the value from the task parameter is copied into the corresponding environment parameter.

  • This allows environment‑level logic (for example, activation scripts or start model scripts) to use the same setting that was configured on the task.

The two objects still keep their own values in the configuration. The forwarding only affects the value used during that particular execution.

Data Shop Order Forms and executable objects

In the Data Shop, form fields are mapped explicitly to the parameters of the executable objects (tasks or workflows) that should be started. When a user submits an order:

  • XDM reads the values from the form fields.

  • The mapped parameters of the selected task or workflow are set to these values before execution.

The Data Shop does not automatically discover parameters. Instead, you define which form field is connected to which parameter of the executable.

Accessing Task Parameters from Rules

Some rule types can access the parameters of the executing task directly. In these cases, rule code can read custom parameters from the task context and use them to control its behavior. Overview of Rules in XDM and Overview of Custom parameters

The exact access pattern depends on the rule type and scripting API. For details, refer to the corresponding rule reference and script reference for the task context.

Using Custom Parameters in your own Scripts

Except for the cases described above, all custom parameters remain local. They are not propagated automatically. However, you can still use them anywhere if you:

  • read the parameter value explicitly in your script or rule, and

  • pass it on to other objects using the available APIs.

Using Custom Parameters in Scripts and Rules

Custom parameters can be used in different parts of XDM: in Data Shop scripts, in rules (for example selection or modification rules) and in workflows or task stage hooks. This section explains where you can access them and how they are typically used.

Using Custom Parameters in Data Shop Scripts

Data shop scripts work primarily with form parameters and with mapped properties of the underlying task or workflow template.

The following data shop scripts are available:

  • Init order script (initOrderScript) – runs before the Data Shop form is displayed first and controls the initial values and look of that form.

  • Revalidation script (revalidationScript) – runs each time the user performs any action to the input fields and can be used to validate inputs and change related fields.

  • Validation script (validationScript) – runs when the order button was clicked to do a final check of the form.

All these scripts work on the data shop form parameters. When the order is placed, the values of the form parameters are written into properties or custom parameters of the selected task template or workflow template via the mappedProperty configuration.

Custom parameters can also be defined directly on the data shop object. In this case they behave in the same way as custom parameters on other XDM objects:

  • They are additional properties of the data shop.

  • They are available in all scripts and hooks that can access the data shop object.

  • They can be used to control behavior or store data

Custom parameters on the data shop are not created as input fields in the order form. If you want end users to enter values interactively, configure form parameters on the data shop and map them to the desired properties or custom parameters on the executed task or workflow template.

Custom Parameters and Data Shop Form Parameters

Custom parameters and data shop form parameters serve different purposes in a data shop:

  • Form parameters define the user interface of the order form:

    • Each form parameter creates an input field in the data shop order form.

    • Data shop scripts (init, revalidation, validation) work directly with these fields and their values.

    • When an order is placed, the value of each form parameter is written to the configured mappedProperty of the underlying task or workflow template. This can be a regular property or a custom parameter on the executable object.

  • Custom parameters are configuration elements on templates and data shops:

    • On task templates and workflow templates, custom parameters are typically used to control execution logic and can be filled from data shop form parameters via mappedProperty.

    • On the data shop itself, custom parameters can hold additional configuration values that can be used in the data shop scripts directly or can be read as property of the data shop, when the data shop object is accessed via XDM’s API.

    • Data shop custom parameters do not create visible or editable form fields and are not part of the form parameter list. Use them for reusable configuration values that are evaluated by scripts, not entered directly by the requester. For interactive user input, define form parameters on the data shop and map them to the required properties or custom parameters on the executed task or workflow template.

Access Patterns for Parameters in Rules

The following overview shows how custom parameters are typically accessed in the different rule types:

Rule type Access via patterns (${…​}) Access via runtime properties

Selection rules

for schema and name patterns

/

Exclude rules

for schema and name patterns

/

Mapping rules

for source selection patterns and target value

in JavaScript target value mode via Packages.de.ubs.xdm.utils.core.RuntimePropertiesUtil.get() for complex mappings

Reduction rules

in Schema/Name/Column pattern and Reduction Expression

/

Modification rules

in Schema/Name/Column pattern and in rule parameters

in JavaScript and Groovy ctx.getTaskRuntimeProperty()

Data apply rules

/

/

Data relation rules

can be used in the Script fields (base table, lookup, referenced table scripts)

You can use script ctx.getTaskRuntimeProperty() in the lookup and base table condition script

Ignore difference rules

for value pattern

/

Extract data rules

for schema, name and column pattern and in output settings output column, Schema, table

/

Column specification rules

for schema, name or column pattern

/

Column exclude rules

for schema, name or column pattern

/

Column property rules

for schema, name or column pattern

/

Entity filter rules

can be used in the Script field (filter script)

/

In addition, scripts and rule methods (for example modification methods, mapping JavaScript, or template‑based reduction rules) can read custom parameters as runtime properties.

As a rule of thumb, custom parameters are used in two main ways:

Via patterns ${parameterName} in rule pattern fields: * In fields that accept schema, name or column patterns, you can reference custom parameters with ${…​}. * Typical examples are selection rules, exclude rules or ignore difference rules where you want to inject parameter values directly into simple patterns.

Via runtime properties in scripts and templates: * In JavaScript, Groovy or SQL templates you can read custom parameter values as runtime properties. * This is typically used when you need conditional logic or calculations, when you want to combine multiple parameter values, or when you must decide at runtime between several target values (for example in mapping rules or template-based reduction rules).

For details on which fields in a specific rule type support patterns or scripts, refer to the corresponding rule reference chapter.

Accessing Custom Parameters in Scripts

Custom parameters are always attached to concrete XDM objects (for example environments, application models, task templates). In scripts custom parameters can be accessed like regular properties of the script context objects.

Which objects are available in a script depends on where the script runs:

Example: Accessing a Shared Custom Parameter in a Groovy Script

In this example, the custom parameter myStartModel is used to decide which installed application should act as the start model in an environment.

The same custom parameter name is used on several objects:

  • On the application model, if it is the start model for a specific scenario, the property myStartModel stores for which scenario this application model is the start model..

  • On the environment, a property such as myStartModel holds the selected start model identifier for that environment.

  • On the task template the same parameter myStartModel is used to specify which start model should be used in the current task execution. The value of myStartModel is automatically given to myStartModel of the environment at runtime.

In the startModelScript of the environment, the environment itself is available as environment. From there, you can access its installed applications and their application models and compare the myStartModel values to find the correct start model.

environment.installedApplication.applicationModel.myStartModel

myStartModel is the custom parameter of the application model that belongs to the installed application.

A Groovy helper method can then read and compare these values:

def getStartModel(def environment) {
    for (def installedApplication in environment.installedApplications) {
        if (installedApplication.applicationModel.myStartModel == environment.myStartModel) {
            // Found the installed application whose application model matches the selected start model
            return installedApplication
        }
    }
    throw new Exception("No start model found for: ${environment.myStartModel}")
}

In this script:

  • environment.myStartModel accesses the custom parameter value on the environment.

  • installedApplication.applicationModel.myStartModel accesses the corresponding value on each application model via the installed applications of the environment.

  • The method loops over all environment.installedApplications and returns the one where both values match.

This pattern shows how to access custom parameters in scripts:

  • Attach the same custom parameter (same internal name) to all relevant objects (application model, environment, task template).

  • Use the generated properties on those objects in your script (for example environment.myStartModel, applicationModel.myStartModel).

  • Implement the logic (comparison, selection, activation) directly in Groovy using these properties.