Data shop

A data shop defines the entry point for a user requesting test data. It describes the form to be filled and the task or workflow template to be executed.

Concepts and more information

Data Shop

Permissions

Data Request Forms 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.
EXECUTE	Specifies that the grantee may execute the object, or schedule the object for later execution. This permission only applies to objects that are executable, i.e. tasks, task templates, workflows, workflow templates, and data shops.
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.
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.

EXECUTE

Specifies that the grantee may execute the object, or schedule the object for later execution. This permission only applies to objects that are executable, i.e. tasks, task templates, workflows, workflow templates, and data shops.

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.

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

Name

Type

Default

Description

Active

active

Boolean

true

Specify whether the data shop is active or inactive. If the data shop is inactive, it can’t be requested. Only users without the PURCHASER role and with execute permissions can use it.

Category

Embedded parameters: formParameters

A data shop can define one or multiple form parameter that must be specified as input parameter when executing or requesting the data shop. It is possible to define more than one form parameter.

A data shop can be configured in such a way that users must specify the business specific values when they execute or request a data shop. For example contract numbers, test case numbers, target environment, etc.

Name	Type	Default	Description
defaultValue	String	n/a	The default value of the form parameter. This value is used as default in the order screen of the data shop as value for the parameter. This property is optional. If no value is specified for the property the default value of the mapped property will be used.
description	String	n/a	An optional description of the form parameter. The description can contain multiple lines to give more context on the configured object. The description of the form parameter is displayed to users that order or request a data shop. It should be specified to give these users more information about the context in which the parameter is used.
displayName	String	n/a	The name of the form parameter. This name is shown in the order screen of the data shop. The name should be application specific and make the use of the parameter clear for the requester.
hidden	Boolean	n/a	Controls whether the form parameter is displayed in the order screen, or not. If the parameter is marked as hidden, the value specified in defaultValue field is used as value for the form parameter. This value is used in the implicitly created task or workflow. A hidden parameter can be used if a requester must not specify a value for it, but the mapped property of the underlying task template or workflow template requires an overwritten value.
mappedProperty	String	n/a	Specifies the property of the specified task template or workflow template that will be overridden by the form parameter. This can be any settings including custom parameters that are defined on the executable object. The value that the user enters for the form parameter when ordering the data shop is overwritten in the implicitly created task or workflow.
optional	Boolean	n/a	Controls if a value must be specified in the order screen, or not. If the parameter is optional the user is not forced to specify a value for it. Only parameters with requirement level of `NONE` can be optional. All other parameters are mandatory.
possibleValues	List	n/a	Specifies a list of possible values for the parameter. The values are entered as pairs of strings. The first string is the actual display name. The second string is a value, which is shown in a drop-down box in the order screen of the data shop. The user that requests a data shop order can choose only by one of these values specified in this list. If the list is empty the user can enter any value allowed for the mapped property.

Name

Type

Default

Description

defaultValue

String

n/a

The default value of the form parameter. This value is used as default in the order screen of the data shop as value for the parameter. This property is optional. If no value is specified for the property the default value of the mapped property will be used.

description

String

n/a

An optional description of the form parameter. The description can contain multiple lines to give more context on the configured object. The description of the form parameter is displayed to users that order or request a data shop. It should be specified to give these users more information about the context in which the parameter is used.

displayName

String

n/a

The name of the form parameter. This name is shown in the order screen of the data shop. The name should be application specific and make the use of the parameter clear for the requester.

hidden

Boolean

n/a

Controls whether the form parameter is displayed in the order screen, or not. If the parameter is marked as hidden, the value specified in defaultValue field is used as value for the form parameter. This value is used in the implicitly created task or workflow.

A hidden parameter can be used if a requester must not specify a value for it, but the mapped property of the underlying task template or workflow template requires an overwritten value.

mappedProperty

String

n/a

Specifies the property of the specified task template or workflow template that will be overridden by the form parameter. This can be any settings including custom parameters that are defined on the executable object. The value that the user enters for the form parameter when ordering the data shop is overwritten in the implicitly created task or workflow.

optional

Boolean

n/a

Controls if a value must be specified in the order screen, or not. If the parameter is optional the user is not forced to specify a value for it. Only parameters with requirement level of NONE can be optional. All other parameters are mandatory.

possibleValues

List

n/a

Specifies a list of possible values for the parameter. The values are entered as pairs of strings. The first string is the actual display name. The second string is a value, which is shown in a drop-down box in the order screen of the data shop.

The user that requests a data shop order can choose only by one of these values specified in this list. If the list is empty the user can enter any value allowed for the mapped property.

Actions

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

List Actions

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

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

Opens a new view on the list that allows the user to specify the ordering of the elements using drag and drop. Confirm the new ordering with Save Changes.

The following permissions are required on the list:

READ
WRITE

Object Actions

The following actions are available on specific data request forms. 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 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

This action creates a task execution for a task or workflow. Place order is deactivated for all users with the purchaser role if the data shop has been set to inactive and the execution permission has been assigned via the purchaser role.

More details about this action can be found here.

The following permissions are required:

EXECUTE
READ

A user can request the execution of a data shop that must be approved by another user. The requesting user must have READ permissions for that data shop. Once the execution is requested, it can be reviewed by an approver. The data shop must also be active so that an execution can be requested.

The approver can either approve the request, which results in an execution being started, or reject the request. The user that can approve, or reject the request must have the EXECUTE permission on the data shop.

More details about the requesting process can be found here.

The following permissions are required:

READ

The simulation of data shop orders is intended for designers who want to verify a data shop order from the view of a different user. While simulating, the data shop behaves exactly as a real order, but finally the order won’t be executed but instead the final settings of the order will be displayed as well as the output of the initialization, revalidation and validation script.

The following permissions are required:

READ
WRITE

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

License Options

This object is available if the following license option is enabled:

COMPONENT:DATA_SHOP

The object is also available if the license package is at least: STANDARD.

Appendix

Examples to format the description

An example to add highlight some words would look like this:

This is __important__ text with some _remarks_.

To add a link to the description use the following syntax:

[UBS Hainer](https://www.ubs-hainer.com) or <https://www.ubs-hainer.com>

To describe the purpose of the data shop in the list and add more detail in the send action page, see this example:

This is the description visible in the list.

The second and all following paragraphs will only be visible inside the send action page.

Examples of task name pattern

The default pattern ${dataShop.displayName} at ${.now?iso_local} will create the task name Example Shop at 2021-09-22T10:31:00+02:00 for a data shop named "Example Shop" executed at the indicated date, time and time zone offset.

With FreeMarker, each access to variables or special FreeMarker functions has to be written in the form ${…}. In the example ${dataShop.displayName} accesses the displayName property of the dataShop variable. The next FreeMarker statement uses FreeMarker’s built-in special variable .now to get the current timestamp and converts this timestamp to a string representation in ISO-8601:2004 format with a call to the FreeMarker function iso_local.

Further information on FreeMarker functions and special variables can be obtained from FreeMarker’s Template Language Reference and the chapter Built-in Reference at https://freemarker.apache.org/docs/ref_builtins.html.

When the data shop is configured to execute a task template, the properties of the template can be accessed. For instance, to obtain the task template’s name you can use ${dataShop.taskTemplate.displayName}.

All data shop parameters are also available as variables in the FreeMarker context. If you configure a form parameter that maps to a custom parameter which defines a variable named custParVarName, this variable can be accessed as ${custParVarName}. If a form parameter maps to a template parameter, you can use XDM internal name of that parameter to access its value. For example, if there is a mapping for a task template’s parameter logLevel, this can be used with the expression ${logLevel}. The internal XDM names of template parameters are mentioned in the template’s reference description in the chapter properties. When accessing a parameter of type connection, environment, or file the display name will be used as a value for that parameter. All other parameters resolve to a string representation of their value.

Request a Data Shop

Permissions on requested execution

The group of users that can approve a requested execution is former known as the approver role. The approver role is responsible for deciding whether the execution can be started or must be rejected.

The user that requested the data shop execution becomes the owner of the requested execution. If a technical user is set up, he becomes the owner of the execution, and the requesting user gets access to the execution. Each user that has the EXECUTE permission on the data shop get access to the requested execution. These users get READ access on the execution and the DELETE permission to approve or reject the request.

In the following table, we see an overview of the permissions granted to the involved users:

User	Permission	Action
Users who requested the data shop execution	Owner	Can access the requested execution
Technical user (if set up)	Owner	Purchaser gets rights on the execution
Users with EXECUTE permission on the data shop	READ and DELETE access	Can approve or reject the requested execution

User

Permission

Action

Users who requested the data shop execution

Owner

Can access the requested execution

Technical user (if set up)

Owner

Purchaser gets rights on the execution

Users with EXECUTE permission on the data shop

READ and DELETE access

Can approve or reject the requested execution

Permissions on approved execution

If the corresponding requested execution is approved, the task execution is scheduled, either immediately or at a later point in time. The user who requested it will have certain permissions on the resulting execution. These permissions determine what actions the user can take on the execution, such as viewing, deleting, etc. The user that requested the data shop execution becomes the owner of the resulting execution. If a technical user is set up, he becomes the owner of the execution, and the purchaser gets rights on the execution.

In the following table, we see an overview of the permissions granted to the involved users:

Action	Owner	Additional Access	Technical User
Requested execution approved by approver	User who requested the execution	-	No
Requested execution approved by approver	Technical user	User who ordered the data shop	Yes
Schedule execution by any user	User who placed the order, on the scheduled execution and the running execution	-	No
Schedule execution by any user	Technical user on the scheduled execution and the running execution	User who ordered the data shop on the scheduled execution and the running execution	Yes

Action

Owner

Additional Access

Technical User

Requested execution approved by approver

User who requested the execution

Requested execution approved by approver

Technical user

User who ordered the data shop

Yes

Schedule execution by any user

User who placed the order, on the scheduled execution and the running execution

Schedule execution by any user

Technical user on the scheduled execution and the running execution

User who ordered the data shop on the scheduled execution and the running execution

Yes

Place a Data Shop order

When a data shop is ordered, several technical processes occur in the background. Here’s an overview of what happens:

The system checks if you have the necessary permissions to execute the underlying task or workflow. If you don’t have the required permissions, the execution is denied, and you won’t be able to proceed. The user that places the order needs the EXECUTE permission on the data shop and READ permission on all dependent objects.

If you have the necessary permissions, the system creates an execution object to represent the running instance of the data shop. The execution object contains metadata about the execution, such as the start time, end time, and status of the execution.
If the data shop has a technical user assigned to it, the system switches the execution context to run under the technical user’s credentials. This means that any code or operations that are executed as part of the data shop will be run under the technical user’s permissions and privileges.
If there are any default permissions declared for the type execution, they are applied to determine the user’s access rights to the execution.
Once the data shop execution is complete, the system updates the execution object with the end time and status of the execution. The system also stores any output generated by the execution, which can be accessed by users with the appropriate permissions.

Permissions on the execution

Permissions are an important aspect of our system that help control access to data and ensure that users have the appropriate level of access to perform their tasks. In the context of data shop executions, permissions are used to determine which users have the right to execute, request, or approve a data shop, and who can access the outputs generated by the data shop execution.

This section will cover the various permissions that are granted by a data shop execution, including the owner permission. We describe how the ownership of an execution object is determined, and how the presence of a technical user can affect permissions. Additionally, we will explore how default permissions can grant additional access to other users on the execution.

Understanding these permissions is crucial to ensuring that users have the necessary access to complete their tasks while maintaining the security and integrity of the data.

If a data shop is executed directly (i.e., not requested), the user who initiates the execution becomes the owner of the execution object. This means that the user has full control over the execution and its output by default.
If the data shop is requested, the user who requests it becomes the owner of the requested execution object. However, the execution itself doesn’t start until an approver approves the request. If the requested execution is approved, it becomes an execution object, and the user who requested it becomes the owner of the execution.
If the data shop has a technical user assigned to it, all executions under that data shop run under the technical user’s credentials. This means that the technical user becomes the owner of the execution object, and the user who requested or executed the data shop gains rights to the execution based on the default permissions assigned to the technical user.
Additional permissions can be assigned to an execution object using default permissions, which dynamically assign permissions to users based on their roles and other attributes.

In summary, the user who initiates or requests the data shop typically becomes the owner of the execution object, but the ownership can change depending on the presence of a technical user or the approval of a requested execution. default permissions can also play a role in determining the access rights of users to the execution object.

The following tables gives an overview of the permissions that are granted to the resulting execution. Belong these the default permissions of type execution are additionally applied.

Action	Owner	Additional Access	Technical User
Direct execution by any user	User who executed the execution	-	No
Direct execution by any user	Technical user	User who ordered the data shop	Yes
Schedule execution by any user	User who placed the order, on the scheduled execution and the running execution	-	No
Schedule execution by any user	Technical user on the scheduled execution and the running execution	User who ordered the data shop on the scheduled execution and the running execution	Yes

Action

Owner

Additional Access

Technical User

Direct execution by any user

User who executed the execution

Direct execution by any user

Technical user

User who ordered the data shop

Yes

Schedule execution by any user

User who placed the order, on the scheduled execution and the running execution

Schedule execution by any user

Technical user on the scheduled execution and the running execution

User who ordered the data shop on the scheduled execution and the running execution

Yes