Environment

An environment specifies a set of applications, which perform together to model some kind of business logic. Typically, you will have a production environment, that runs the actual business process and multiple layers of other environments like pre-production, integration test, acceptance test, development, training and so on. XDM allows you to define those environments by specifying the applications running on a certain database.

Using environments as source and/or target

When using an environment in a task template or task, it can be used as a source environment or as a target environment. However, it can be undesirable to permit writing to certain environments (e.g. production).

In XDM it is possible to solve this situation with permissions. An environment has two additional permissions named Use as source and Use as Target. For every user or role it is possible to set this permission individually. If Use as source is set on an environment for a specific user, the environment can be used by that user as a source environment, but not as a target environment, when creating a task or task template, or when executing a task.

Concepts and more information

Environments and application models

Permissions

Environments 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.
READ	Specifies that the grantee has read permission on the object. The grantee is able to see the object in lists and can see all of the object’s details, such as rules or access permissions. In addition, the grantee can reference this object. For example, a user who has `READ` permission on a credential object can refer to this credential object when creating a new database connection.
SOURCE_USAGE	Specifies that the object can be used as the source for an XDM task. This permission only applies to environments and connections. If a user does not have the `SOURCE_USAGE` privilege for an environment or connection, it is not displayed in the drop-down list where the source environment or connection for a task needs to be selected.
TARGET_USAGE	Specifies that the object can be used as the target for an XDM task. This permission only applies to environments and connections. If a user does not have the `TARGET_USAGE` privilege for an environment or connection, it is not displayed in the drop-down list where the target environment or connection for a task needs to be selected.
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).

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.

READ

Specifies that the grantee has read permission on the object. The grantee is able to see the object in lists and can see all of the object’s details, such as rules or access permissions.

In addition, the grantee can reference this object. For example, a user who has READ permission on a credential object can refer to this credential object when creating a new database connection.

SOURCE_USAGE

Specifies that the object can be used as the source for an XDM task. This permission only applies to environments and connections. If a user does not have the SOURCE_USAGE privilege for an environment or connection, it is not displayed in the drop-down list where the source environment or connection for a task needs to be selected.

TARGET_USAGE

Specifies that the object can be used as the target for an XDM task. This permission only applies to environments and connections. If a user does not have the TARGET_USAGE privilege for an environment or connection, it is not displayed in the drop-down list where the target environment or connection for a task needs to be selected.

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 environments. The 'name' column displays the property name as it can be used in Groovy and Java Scripts.

Name

Type

Default

Description

Activation script

activationScript

String

n/a

A JavaScript or Groovy code snippet that is used to dynamically skip installed applications during task execution. This script determines whether an installed application defined on the current environment should be considered by a task execution.

The script has access to the environment’s variables and custom parameters, as well as the variables and custom parameters of the installed application.

The script can be used to configure an environment so that, using custom parameters, the user can determine which installed applications are to be used for a task execution and which are not. The task uses the activation script to decide dynamically which parts of an application should be copied. The parameters are evaluated during execution and used by the activation script to control the copy process. Custom parameters that are defined on the environment can be overwritten on task template or task level.

More details about the script can be found here.

Automatic data reservation

automaticDataReservation

Boolean

false

This option controls the automatic creation of the data reservation for the environment. If this option is active, XDM automatically creates data reservations for the generated data at the end of a task execution. You should activate this option if you want to prevent unauthorized users from changing or deleting your data.

Data reservation duration

dataReservationDuration

String

n/a

Specifies the duration of a data reservation. The data reservation is active immediately after the completion of the task execution.

A detailed description of the period syntax can be found here.

Data reservation name pattern

dataReservationNamePattern

String

Reserved data by ${taskTemplate.displayName}-${task.displayName}

This pattern is used to control the name of implicit created data reservations. If the property automaticDataReservation is active a data reservation is created each time data is copied into the environment. The name of the created reservation is generated based on this name pattern.

The resulting name must be unique. No two reservations with the same name can exist. An existing reservation might be replaced, if a reservation with the same name already exists while a task execution tries to create a new reservation with the same name. The precondition, that the current user has the WRITE and MODIFY_DATA permission on the existing reservation, must be fulfilled.

This pattern allows the specification of FreeMarker expressions. XDM evaluates this expression and replaces the used variables. Details about the available variables can be found at variables.

Available variables for the data reservation name pattern

Task template (taskTemplate): The task with all its properties.
Task template parameter: All task template parameters are available for use in the name pattern.
Task (task): The task with all its properties.
Task parameter: All task parameters are available for use in the name pattern.
Environment (environment): The environment with all its properties.
Execution Number (autoIncrement): This increasing number is a unique identification number for an execution.

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

Specifies the name of the object. The name is used to display and identify the object in lists. The name can contain any valid UTF-8 characters. This field is mandatory.

Libraries

libraries

File

n/a

A list of files that can be accessed in the start model script or activation script code. When editing the environment, all XDM files of the specified script language are made available for selection. The content of the selected XDM files is automatically added to the script context. All methods, variables, and classes in the selected files can be accessed in the validation script.

Modification sets

modificationSets

ModificationSet

n/a

The property contains a list of modification sets that can be used to modify data during the task execution. For every modification set it is also stored, if it is selected or not. Only selected modification sets are shown in the view mode of the object.

Script language

scriptLanguage

Enum

JAVA_SCRIPT

This script language specifies in which language all scripts of the object are written. Currently the following languages are supported:

Groovy (GROOVY): specifies that the code is written in Groovy.
JavaScript (JS): specifies that the code is a JavaScript.

Start model

startModel

Reference

n/a

Specifies the name of the start model. The start model defines which application model and which version is to be used as the starting point for data selection when the environment is used as a source environment.

This field can only be specified if Start model selection is set to Static.

Start model script

startModelScript

String

n/a

A JavaScript or Groovy code snippet that is used to determine the start model. The script is executed at the start of a task execution. It must return one of the environment’s installed application entries. The returned entry will be treated as the start model for the task execution.

This field can only be specified if the Start model selection is set to Dynamic.

More details about the script can be found here.

Start model selection type

startModelSelection

String

STATIC

Specifies how the start model is selected. This property can have the following values:

Dynamic: In contrast to the option Static this option allows dynamic selection of the start model. The start model is determined by the Start model script. This script is evaluated at the start of task execution and must return an installed application of the environment.
Static: The start model is specified by the startModel field of the environment. The value is explicitly specified by the user and will always be the same.

Tags

Actions

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

List Actions

The following actions are available on the environments 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 environments. 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.

This action validates the object and its dependencies, reporting configuration errors that could cause issues during task or workflow execution. The validation will cascade through the child objects of the checked objects and objects referenced by them.

For instance, if an installed application of an environment is checked, the check will process the application model, the specified version, the connection, modification sets, and involved modification methods. If an object has rules, all active rules will be checked. The modeling connection and version, including their modification sets and methods, will also be checked. Deactivated objects will not be included in recursive checks, but can be checked individually if the check is executed on the object itself.

Checks often require additional information from the context of the objects being checked, such as necessary connections or custom parameter values. The check will gather information from the objects being checked and use it to perform checks on child objects. Any required additional information must be provided before the check begins. The check queries the user to provide these missing information.

Database object checks: For all rules which reference database objects such as tables, columns, etc, the check verifies that the those objects exist in the database system. If a connection can be inferred from the context, then this connection is used. If no connection is available in the context, it must be specified before the check is executed.
Connection checks: For objects which configure access to external systems, such as connections or storage locations, the configuration check verifies that access can be established using the given credentials. Furthermore, additional operations on database connections are performed to check whether the credential user has the necessary authorization to access relevant database objects. In particular, the credential user’s permission to read source tables and write to target tables is verified. Similarly, for storage locations the check verifies that the credential user has permission to write to the working directory.
Code checks: For all entities containing code segments, such as modification methods or condition scripts, the syntax for the code is checked. This does not check, however, whether at run time all necessary variables are likely to be available.

The following permissions are required:

READ

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.

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

Will create an exact copy of the current object with a different display name in the same list. Users can decide whether they want to copy child objects like rules, permissions or tasks. It is only possible to select complete classes of objects and not to select individual child objects. Copied child-objects will preserve their display name. The default is to copy all child objects.

The following permissions are required:

CREATE
READ

Opens the current entity in edit mode.

The following permissions are required:

READ
WRITE

This diagram shows the relationships between the installed applications. Only those relationships are shown that have data relation rules in the application model version that reference another application model. Other data relation rules without an application model are therefore not visible in the diagram. The installed application, which is the start model, is highlighted graphically, and inactive rules are represented by light gray arrows.

The following permissions are required:

READ

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

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

Appendix

Toleration mode examples

In the following, the two toleration modes are explained using two different environments, and what effect the two modes STRICT and INTERSECTION have on the execution.

The following table shows two environments 'Insurance-Full' and 'Insurance-Small', which have a different number of installed applications.

Insurance-Full

Insurance-Small

Car insurance

Life insurance

Term insurance

Accident insurance

Liability insurance

STRICT - STRICT

It is not possible to copy the environments because both environments have been set to STRICT. Thus, it is expected that all installed applications from the source also exist in the target environment.

Copy cannot be executed, because the two installed applications 'Car Insurance' and 'Liability Insurance' are missing in the target environment 'Insurance-Small', and thus the two environments do not match.

INTERSECTION - INTERSECTION

A copy can be executed successfully because the three installed applications 'Life Insurance', 'Risk Insurance' and 'Accident Insurance' from the target environment are an intersection of the source environment. So only the data from these three applications will be copied to the target database.

Copy can be executed, because the target environment has an intersection of the source environment at installed applications.

INTERSECTION - STRICT

A copy can be executed successfully because the three installed applications 'Life Insurance', 'Term Insurance' and 'Accident Insurance' from the target environment exist in the source environment, and therefore are an intersection of the source. So only the data from these three applications will be copied to the target database.

Copy can be executed, because all installed applications of the target environment are an intersection of the applications from the source environment.

STRICT - INTERSECTION

It is not possible to copy the environments because the source environment is set to STRICT. This means that all installed applications from the source must exist in the target environment. This is not the case because the two applications 'Car Insurance' and 'Liability Insurance' are missing.