Custom parameter

A custom parameter defines a variable to be used in task and workflow templates. They can be used to model user specific behavior in rules and scripts. Also, they can be used to define the objects or data in task executions.

Permissions

Custom Parameters have specific permissions to manage user access. The table below displays the available permissions and their purposes.

For more details about the concept of XDMs permission management refer to Permission Management.

Permission

Description

ADMINISTRATION

Specifies that the grantee can grant and revoke permissions to and from other users.

A user that creates an object automatically receives the ADMINISTRATION permission on that object.

DELETE

Specifies that the grantee can delete objects of the selected types.

WRITE

Specifies that the grantee has the permission to change the settings and attributes of an object. This also includes modifying any rule lists that might be associated with the object (for example, the selection rules of a task template).

Properties

The table below documents the available properties for custom parameters. The 'name' column displays the property name as it can be used in Groovy and Java Scripts.

Name

Type

Default

Description

Default value

defaultValue

String

n/a

This is the default value used if no value is defined manually.

Description

description

String

n/a

An optional description for this object. The description can contain multiple lines to give more context on the configured object. The description is not used in a technical context.

Name

displayName

String

n/a

This is the name that is used in selection lists. These names are never used in a technical context, so spaces and symbols can be used. This field is mandatory. The display name has a maximum length of 128 characters.

Dynamic Option Entry

dynamicOptionEntry

Boolean

false

Defines whether option entries are dynamically created every time the user could change the value of the custom parameter or if the query execution must be triggered by the user.

Option Entry Connection

optionEntryConnection

Connection

n/a

Specify a connection on which the SQL query is executed.

Option Entry Expression

optionEntryExpression

String

n/a

Define a SQL query which is executed on the specified connection to create the option entries. The query has to return two columns. The first column contains the display name. There are no NULL values allowed. The second column contains the corresponding values. Both columns must be of a string or character type (VARCHAR, TEXT, …​)

Option Entry Result Limit

optionEntryResultLimit

Number

100

Controls the maximum number of rows to fetch when the option entries are determined dynamically by an SQL query.

Parameter type

parameterType

DataType

STRING

This property defines the type of the parameter. The following types can be specified:

Boolean

A binary parameter that can have one of two possible values: 0 (false) and 1 (true).

Collection

A string containing a comma-separated list of values.

Connection

An XDM Connection. Further details can be found in the XDM Connection reference documentation.

Date

A date in the format YYYY-MM-DD

Environment

An XDM Environment. Further details can be found in the XDM Environment reference documentation.

File

An XDM File. Further details can be found in the XDM File reference documentation

Number

This parameter type only accepts integer values.

String

The string parameter type has a maximum length of 256 characters.

TimeStamp

A timestamp in the ISO 8601 format. It has the following syntax: YYYY-MM-DDTHH:MM:SS

Requirement level

requirementLevel

RequirementLevel

NONE

This property defines at which time the value must be specified. The following options are available:

INITIALLY

It is necessary that the parameter has a value as soon as the object is created. For example, this means that a modification method using such a parameter cannot be saved if the parameter has no value.

NONE

There is no requirement to set this parameter.

RUNTIME

The parameter must have a value when a task using that parameter is executed. The same applies for hooks and workflows.

Tags

tags

Tag

n/a

Contains the tags that apply to this object. These tags can be used in the search to find objects quickly and effortlessly.

Validation expression

validationExpression

String

n/a

Validation expression corresponds to a regular expression. This expression can be edited only if the validation type is set to regular expression.

Validation type

validationType

ValidationType

NONE

Validation expression corresponds to a regular expression. This expression can be edited only if the validation type is set to regular expression.

Variable

variableName

String

n/a

This is the variable name under which the custom parameter is accessed in modification methods, reduction rules, start conditions, and so on. These names are used in a technical context, so spaces and symbols cannot be used. Furthermore, this value must not start with a number. This field is mandatory. The variable name has a maximum length of 128 characters.

Embedded parameters: options

A list of possible options, from which the user can select, when a value for the custom parameter must be specified. The list of options is displayed as a drop down box in the user interface and the user can select on the available options.

Name

Type

Default

Description

displayName

String

n/a

The display name of the option that is presented in drop down boxes in the user interface.

value

String

n/a

Specifies a value that can be used for the custom parameter.

Actions

The available actions are described below. Some actions apply to the list, while others are specific to selected custom parameters.

List Actions

The following actions are available on the custom parameters list. If the action is disabled a tooltip will provide the exact reason for the deactivation. The required permissions are described in detail for each action.

  • Bulk Create Permission

  • Bulk Delete

  • Bulk Export

  • Create

  • List History

Create a new permission on the selected objects. Shows in the result list whether the permission could be granted on the respective object. Only these permissions can be granted that are existing on the underlying object.

A permission in the result list can have three different states, these are:

CREATED

The permission successfully granted on the object.

MERGED

The granted permission already exists on the object and merged with the new permission.

SKIPPED

The permission could not be granted, because of missing administration permission on the object.

The following permissions are required on the list:

  • ADMINISTRATION

  • READ

Delete the selected objects.

The following options are available:

Cascade

Recursively delete depending objects.

When using cascade, dependent objects are deleted first also with cascade enabled. Thus, a cascade deletion is a recursive function that deeply searches for dependent objects and deletes them first. There is only a confirmation for the first object. The dependent objects are deleted without confirmation but only when the user has the DELETE permission.

This feature is only available in development mode. More information about development mode can be found in the chapter User Settings. It should be used with caution.

An object in the result list can have two different states, these are:

DELETED

The object could be deleted.

NOT_DELETED

The object could be not deleted. This may be because the executing person does not have a delete permission on the object or the object is still referenced by others. A detailed reason can be determined with the help of the error message. If the object is still in use, these objects are also displayed.

The following permissions are required on the list:

  • DELETE

  • READ

Exports the selected objects.

YAML

Generates a YAML file containing all the object’s settings. The user has the option to download the export file, or to paste the content in the import dialog. The YAML export is particularly suitable for importing the exported objects again via the XDM UI.

ZIP

This export writes several individual YAML-files. Each YAML-file is stored in a directory according to its type. For example, when exporting a native table backup task template named 'A backup template', a YAML-file 'A backup template.yaml' is created inside the directory /TaskTemplate/native-table-backup-task-template/ of the ZIP-file. This kind of export is suitable for usage in git-repositories together with XDM’s configuration as code feature.

Related and dependent objects can optionally be included in the export. The export dialog has the following options:

Include dependent objects

Dependent objects only belong to the exported object like rules and tasks.

Include permissions

Permissions of each exported object, only when the object supports permissions. Some objects like rules don’t have permissions.

Include referenced objects

Referenced objects exist by their own and are used in the exported object like connections and environments.

Include objects that depend on referenced objects

Also include the dependent objects of the referenced objects. E.g. the rules of a modification set or the rules in an application model version.

Objects on which the user does not have READ permission are not exported. This includes dependent and referenced objects. However, the reference to an object will be exported. For example a connection object would refer to the credential, even if the user does not have READ permission on the credential. The definition of the credential object itself will not be part of the export file. This can lead to issues during the import, because the connection cannot be created without an existing credential.

The following permissions are required on the list:

  • READ

Creates a new object in the current list. Depending on the object type either a popup dialog is shown for the most important settings, or the complete object is shown in edit mode. The dialog provides the option to create the object and remain in the current list or to switch to the newly created object in edit mode to perform further changes.

The following permissions are required on the list:

  • CREATE

The history list tracks all modifications made to objects within it. A new record is added each time an object is created, edited, or deleted. A record indicates who made the change, which object was affected, and when the change was made.

For more information about the concept of the history refer to the history concepts.

The following permissions are required on the list:

  • READ

Object Actions

The following actions are available on specific custom parameters. In order to execute the action, the user must possess the necessary permissions for the object. The permissions required for each action are described individually. If the user does not have these permissions, the action will be disabled and the tooltip will provide the exact reason for the deactivation.

  • Delete

  • Edit

  • Event List

  • Export

  • Fetch Option Entries

  • Object History

  • Permission Check

  • Usage

  • Uses

Delete the object. If the object is still used by another entity, an error message is displayed, and the object is not deleted. The delete operation must be confirmed in a separate popup.

The following options are available:

Cascade

Recursively delete depending objects.

When using cascade, dependent objects are deleted first also with cascade enabled. Thus, a cascade deletion is a recursive function that deeply searches for dependent objects and deletes them first. There is only a confirmation for the first object. The dependent objects are deleted without confirmation but only when the user has the DELETE permission.

This feature is only available in development mode. More information about development mode can be found in the chapter User Settings. It should be used with caution.

The following permissions are required:

  • DELETE

  • READ

Opens the current entity in edit mode.

The following permissions are required:

  • READ

  • WRITE

This list shows all registered events for the object. It includes events that are specific to the object, or for that type.

The following permissions are required:

  • READ

This action allows to export XDM objects in different formats in order to import them via export or CasC in another environment.

Refer to configuration of export for more information.

Related and dependent objects can optionally be included in the export. The export dialog has the following options:

Include dependent objects

Dependent objects only belong to the exported object like rules and tasks.

Include permissions

Permissions of each exported object, only when the object supports permissions. Some objects like rules don’t have permissions.

Include referenced objects

Referenced objects exist by their own and are used in the exported object like connections and environments.

Include objects that depend on referenced objects

Also include the dependent objects of the referenced objects. E.g. the rules of a modification set or the rules in an application model version.

Include implicit created objects

Implicit created objects are tasks or workflows which were automatically created for execution. These objects won’t be exported by default, but can be included by setting this flag. When exporting implicit objects, make sure that the Include dependent objects flag is also enabled.

Objects on which the user does not have READ permission are not exported. This includes dependent and referenced objects. However, the reference to an object will be exported.

For example a connection object would refer to the credential, even if the user does not have READ permission on the credential. The definition of the credential object itself will not be part of the export file. This can lead to issues during the import, because the connection cannot be created without an existing credential.

The following permissions are required:

  • READ

Uses the specified query on the given connection to fetch option entries from the database. This can be used as a preview of the option entries, when not using the dynamically create feature. Alternatively this action can be used to initially create option entries. But all already existing option entries will be replaced.

The following permissions are required:

  • BROWSE (on connection)

  • READ

The history displays all changes made to the respective XDM object, including any changes made to its rules.

Each change record includes information about the operation performed (e.g. CREATE, UPDATE, DELETE), the timestamp, and the user responsible for the change.

For more information about the concept of the history refer to the history concepts.

The following permissions are required:

  • READ

The check verifies that the current user has the authorization to access the object. The check can also be performed for a specific user or role, if needed. By default, the check is performed using the current user’s credentials. It is then applied to child and referenced objects.

Additional permission checks are applied when these can be inferred from the context in which the check was started. For example, if the check is performed on a table copy task, the referenced source and target connections are checked to determine whether the given identity has source or target usage permission respectively.

The following permissions are required:

  • READ

The Usage List shows all objects that refer to the current object. It provides an overview of the relationships and makes it easy to track these relationships.

The following permissions are required:

  • READ

The Uses List shows all objects that the current object uses. It provides an overview of the relationships and makes it easy to track these relationships.

The following permissions are required:

  • READ