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 (see Import assets). They are not applied with the Drafts and then publish or Publish directly data states, or when Run validations only is selected.

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).
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. The following example remaps source names and JDBC connection URLs from a development environment to production:

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

These mappings are applied automatically during import. The rules for each property are applied in order, and the first matching pattern is used. A rule defined on a parent asset also applies to all its child assets.

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?