Configure Environment Mapping

Environment mapping translates environment-specific references (such as database names, connection strings, and schema names) between environments during import. This is what allows assets exported from one environment to work correctly in another.

There is no default mapping: you must configure mappings manually before import. Use mappings to connect sources, tables, users, or other references that differ between environments.

Environment mappings are applied only when assets are imported with the Drafts data state, including when Run validations only is selected with that data state (see Import assets). They are not applied with the Drafts and then publish or Publish directly data states.

Configure mappings

To configure mappings:

Go to Global Settings > Application Settings > Import and Export.
On the Settings tab, in Mappings, select Create.
In Create Export Import Mapping, configure the following:
- From database id: The source database identifier from the export archive. You can find it in the databaseId field of the archive-header.json file in the archive.
- Custom mappings: Manual source ID to target ID mappings in JSON format. Use these mappings to link an exported asset to a specific existing asset in the target environment. If both fields contain the same source ID, this field takes precedence over Generated ids mappings.
- Generated ids mappings: ID mappings recorded automatically by previous imports, in the same source ID to target ID JSON format as Custom mappings.
  
  When an import matches an exported asset to an asset in the target environment, the ID pair is recorded here so that subsequent imports resolve the same asset directly by ID. These mappings are maintained by ONE: you do not need to author or edit them manually.
- Scalar remappings for references: JSON rules to transform string values during import (supports regular expressions).
- Reference remappings: JSON rules that redirect a reference to a different target asset during import (for example, a stewardship group). Unlike Scalar remappings for references, which transform string property values, reference remappings replace the whole referenced asset. See Reference remappings.
Select Save and publish.

If mappings are not applied correctly during import, see Environment mappings not applied for troubleshooting steps.

Example: ID mappings

Use Custom mappings to declare that an exported asset and an existing asset in the target environment are the same one:

{
  "<source_asset_id>": "<target_asset_id>"
}

This is the recommended way to resolve import violations caused by failed or ambiguous matching. See Resolve import violations.

The Generated ids mappings field stores ID pairs in the same format. Each import records which target asset every imported ID was resolved to, and subsequent imports reuse these pairs automatically.

Example: Regular expression remappings

Use Scalar remappings for references to transform property values during import. You can define rules for any text property of any asset type. Each set of rules is keyed by <asset_type>.<property>, using the asset type and property names from the export archive, for example source.name or term.name.

The following example remaps source names and JDBC connection strings from a development environment to production:

{
  "source.name": [
    { "pattern": "(.*)_dev", "replacement": "$1_prod" },
    { "pattern": "dev_(.*)", "replacement": "prod_$1" }
  ],
  "jdbcConnection.jdbc": [
    { "pattern": "jdbc:postgresql://dev-db:5432/(.*)", "replacement": "jdbc:postgresql://prod-db:5432/$1" }
  ]
}

These mappings are applied automatically during import, as follows:

A pattern must match the whole value, not just a substring.
The rules for each property are applied in order, and the first matching pattern is used.
A rule defined on a parent asset type also applies to all its child asset types. For example, a rule on connection also applies to jdbcConnection.
Only the rules of the most specific asset type that has rules for the property are used. If none of its patterns match, the rules of its parent asset types aren’t tried.

Reference remappings

Use Reference remappings to redirect a reference to a different target asset during import. This is useful when a referenced asset cannot be matched automatically or must point to a specific asset in the target environment.

Reference remappings differ from Scalar remappings for references in two ways:

They replace the whole referenced asset, not just a string property value.
They are applied only when resolving references (setting an asset’s reference to another asset), never when matching the imported assets themselves.

Reference remappings are currently applied only to single-value references: array references, where a property holds multiple referenced assets, are not remapped.

Configuration structure

The configuration is a JSON object keyed by the owning asset type and the reference property, each holding an ordered list of rules:

{
  "<owning_asset_type>": {
    "<reference_property>": [
      {
        "source": { "key": <reference_key> },
        "target": { "key": <reference_key> }
      }
    ]
  }
}

<owning_asset_type>: Regular expression matched against the type of asset that holds the reference, such as rule. Use ".*" to match any asset type.
<reference_property>: Regular expression matched against the name of the reference property, such as stewardship.
source: A template matched against the exported reference. It only decides whether the rule applies: it never creates or changes the referenced asset.
target: The reference to use instead.

The first rule whose asset type and reference property patterns both match, and whose source matches the exported reference, is applied. Keep in mind that all values in source are regular expressions, whereas all values in target are literal.

Reference keys

Both source and target use the same reference key structure as the export archive:

"key": {
  "path": "<node_path>",
  "id": "<asset_id>",
  "properties": {
    "<scalar_property>": "<value>",
    "<reference_property>": { "key": <reference_key> }
  },
  "childKey": {
    "property": "<embedding_property>",
    "id": "<asset_id>",
    "properties": { "<scalar_property>": "<value>" },
    "childKey": <child_key>
  }
}

path: The absolute path of the referenced asset type, such as /userManagement/groups.
id: The ID of the referenced asset.
properties: Identifying properties of the referenced asset. A scalar property is matched by value, such as "name": "Data Office". A property whose value is an object with a key is a reference to another asset, such as a group’s parent, and contains a nested reference key of its own.
childKey: Identifies an asset embedded inside another asset’s property, such as an item in an array. property names the embedding property, and childKey elements can be nested for deeper structures. Use childKey only for embedded assets: for example, group hierarchy is expressed through the parent reference property, not through childKey.

The outermost key identifies the referenced asset itself, unless a childKey is present. In that case, the outer levels identify the containing assets and the innermost childKey identifies the referenced asset.

Source matching rules

Every string in the source template (path, id, and each scalar property value) is a regular expression. A pattern must match the whole value, not just a substring: for example, to match Data Office, use .* Office, not Office.
Any field you omit acts as a wildcard, so specify only what must match.
Nested reference properties, such as parent, are matched recursively using the same rules.
In a childKey, only the content of the embedding assets is matched (their id, path, and properties); the property name itself is not checked.

Target resolution rules

The target reference fully replaces the matched reference and is resolved the standard way: first by ID, then by matching properties.

All values are literal, not regular expressions.
Every reference key must include a path, including nested reference keys such as a parent.
In a childKey, the property field is required.
The target must resolve in the target environment, otherwise the import fails. Missing assets, such as groups, are never created automatically.

Example

The following configuration remaps the stewardship group of rules and monitoring projects during import. Two rules are defined and tried in order:

Match the exported group by its name and parent hierarchy (Data Office under Marketing under Organization) and remap it to a group named Data Governance Office that exists in the target environment directly under Organization.
As a fallback, match a specific exported group by ID and remap it to a specific target group by ID.

{
  "(rule|monitoringProject)": {
    "stewardship": [
      {
        "source": {
          "key": {
            "path": "/userManagement/groups",
            "properties": {
              "name": "Data Office",
              "parent": {
                "key": {
                  "path": "/userManagement/groups",
                  "properties": {
                    "name": "Marketing",
                    "parent": {
                      "key": {
                        "path": "/userManagement/groups",
                        "properties": { "name": "Organization" }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "target": {
          "key": {
            "path": "/userManagement/groups",
            "properties": {
              "name": "Data Governance Office",
              "parent": {
                "key": {
                  "path": "/userManagement/groups",
                  "properties": { "name": "Organization" }
                }
              }
            }
          }
        }
      },
      {
        "source": { "key": { "path": "/userManagement/groups", "id": "<source_group_id>" } },
        "target": { "key": { "path": "/userManagement/groups", "id": "<target_group_id>" } }
      }
    ]
  }
}

In this configuration:

"(rule|monitoringProject)" limits the remapping to rules and monitoring projects. Use ".*" to apply it to any asset that references a group.
"stewardship" is the reference property being remapped.
In the first rule, the source matches only groups named Data Office whose parent chain is Marketing, then Organization. A group named Data Office elsewhere in the hierarchy is left untouched.

Because no id is given, the match does not depend on the IDs used in the source environment.
The target uses the name and parent of an existing group in the target environment. If no such group exists, the import fails.
The second rule shows ID-based remapping, which is useful when you already know both IDs, for example, from the Generated ids mappings recorded by a previous import.

Next steps

Promote Assets - Export assets from the source environment and import them into the target.
Resolve Import Conflicts - Handle conflicts and validation errors that occur during import.

Was this page useful?