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.

Default naming conventions

If your environments follow standard naming conventions with prefixes or suffixes, environment mapping works automatically. No manual configuration is needed.

For example:

Development: source-dev, schema-dev.
Test: source-test, schema-test.
Production: source-prod, schema-prod.

When assets are imported, ONE automatically detects and remaps these references based on the environment label.

Manual environment mapping

If your environments do not follow standard naming conventions, you must configure environment mappings manually before import. Use mappings to connect sources, tables, users, or other references that differ between environments.

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.
- 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.
- 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.

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?