Mapping table container

A mapping table container is a dedicated database primarily used to store data for masking purposes. The database can be accessed in task stage hooks and modification methods.

The contents of the mapping table container are maintained by XDM, and they are stored at the configured blob store. XDM injects the current state of the mapping tables, to each task execution, that needs access to it. If the task execution modifies the data it is synchronized with the blob store.

We recommend to populate the contents of a mapping table container by a task stage hook. Modification methods should only read from the mapping table container. This approach makes it easier to synchronize access to the mapping table.

Modification Examples

There are scripts for typical use cases and best practices for the population and usage of a mapping table container.

Permissions

Mapping Table Containers 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.

BROWSE

Specifies that the grantee is allowed to see the contents of database tables when using the schema browser, and when inspecting the output of an XDM task that provides a data preview. This permission only applies to connections.

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.

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

Name

Type

Default

Description

Blob store path

blobStorePath

String

n/a

The internal storage path of the mapping table container. XDM uses this path to persist the contents of the mapping tables.

Credential

credential

Credential

n/a

A credential that is used to secure the access to the mapping table contents. The credentials are used to initialize the mapping table database. Only the specified user / password has granted access to the mapping table.

If an external database is uploaded, the credentials must match to the used user/password of the uploaded file.

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.

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.

Variable

variableName

String

n/a

The variable name that is used in modification methods and task stage hooks to access the mapping table container. The variable name must be a valid Java Script or Groovy identifier. XDM will inject an establish JDBC connection object into the respective script. The user can create and drop tables in that database and can insert/update/delete existing rows.

Actions

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

List Actions

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

  • Clear Container

  • Delete

  • Download Container

  • Edit

  • Event List

  • Export

  • Object History

  • Upload Container

  • Usage

  • Uses

Clears the contents of the mapping table container. All tables and their contents are purged by this action.

The following permissions are required:

  • READ

  • WRITE

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

Downloads the content of the mapping table container. The resulting file is an H2 database that contains all tables and their contents.

The following permissions are required:

  • 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

Replaces the contents of the mapping table container. The upload action requires an H2 database file. The content of the H2 database will become the new content of the mapping table container. All tables that are defined in the respective file, can be accessed by XDM’s scripts, like modification methods and task stage hooks.

The user and password of the specified credential must match the credentials that were used to initially create the provided H2 database.

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

Backup and Migration of Mapping Table Containers

Mapping table containers are usually backed up as part of the installation directory backup. When this backup is restored, these are also restored accordingly. If mapping table containers are to be transferred to another environment or backed up outside of the complete backup and then restored, a different method is required:

  1. Exporting the mapping table container to a YAML file or ZIP file

  2. Download of the mapping table content as file.

  3. Importing the exported mapping table container

  4. Upload the file with the mapping table content

Exporting MTC Object Structures

In the user interface, you can export the structure of a Mapping Table Container. This export includes the metadata (structure and configuration), but does not include the actual data files associated with the Mapping Table Containers.

When importing these exported structures into a system, each imported MTC is assigned a new UUID. As a result, the associated files are stored under a new identifier on the server.

Be aware: - If the database remains unchanged and only the files are backed up directly (without import/export), their association remains valid. - If you import MTC objects into a new system or fresh installation, the changed UUIDs mean that files may no longer be linked correctly.

Backing Up Complete MTC Data

To fully backup Mapping Table Containers, including their data, you have two options:

  1. File Backup of Database (mv.db) Download the H2 database files (e.g., mv.db). This method preserves all relationships, including UUIDs. Restoring by uploading these files will allow you to recover all mapping containers, preserving file associations.

  2. Direct Data Download from Interface Use the user interface to navigate to each Mapping Table Container and download its contents. This way, you obtain a copy of the container data. Note: This is a manual process and may not be selective for single-object restores.

Restore and Migration Scenarios

  • Restore on Same Environment: As long as the database (and therefore the UUIDs) remains the same, restoring the backed-up files re-establishes the Mapping Table Containers and their file associations without issues.

  • Restore on New/Fresh Installation: When Mapping Table Containers are imported into a different or new environment, new UUIDs are generated. This breaks references to old data files. In such cases, restore should be performed using the complete database backup (by uploading the mv.db files), so that UUIDs and all associations are maintained.

Summary

  • For regular backup/restore operations, always back up the relevant database files in addition to optional MTC structure exports.

  • For migrations between environments or targeted object restores (e.g., as required by specific customers), prefer backing up and restoring the database files instead of relying on exports/imports alone.

  • Remember: Exporting only saves the MTC structure, not the data.