Skip to main content
Version: Next

Mapping Bundles

A mapping bundle is a single file containing everything that makes one migration work: the field mappings, their value translations and When conditions, the relationship transfers, and the export options. Exporting a bundle lets you keep a mapping set as a backup, move it to another Cortex instance, hand it to a colleague, or - because the file is plain XML - build a large mapping set outside Cortex and import it.

Exporting and importing​

WhereWhat it does
Migrate Data screen, Run export sectionExport bundle… downloads the mappings and options currently on the screen. Import bundle… applies a bundle file to the screen you are on.
Utilities → Migration configurationsExport on a saved row downloads that configuration as a bundle. Import bundle… reads a bundle file, resolves its data sources and tables, then opens the Migrate Data screen pre-loaded so you can review before saving.

An exported file is named after its source, for example MigrationBundle_Cherwell_Incident.xml. Import accepts files up to 10 MB.

Why a bundle can be re-bound​

A bundle does not only record the internal identifiers of the data source and table it was built against - it also records their names and types. That is what lets the same mapping set survive the common cases where the identifiers no longer match: a rebuilt test container, a data source re-imported with a new identifier, or a different Cortex instance entirely.

On import, Cortex resolves each piece of the bundle in this order:

  1. Target data source - the original data source if it still exists. If it does not, and exactly one enabled data source of the same type exists, that one is used. If several exist, Cortex asks you to choose one (Data source, then Use data source). If none exists, the import stops and asks you to add the target data source first.
  2. Target table - by identifier, then by name.
  3. Field mappings - re-bound by field identifier, then by display name. A mapping whose target field no longer exists on the table is cleared rather than left pointing at a field that is gone; its row stays so you can re-point it. The same applies to a source field that can no longer be resolved.
  4. Relationship transfers - re-bound by their stable key, then by display name, and the child field mappings inside each transfer are re-bound the same way. A transfer that cannot be resolved on both sides is left exactly as it was and reported back to you.

When the import finishes, a Migration bundle imported message summarises the result: how many mappings were re-bound, how many were re-matched by name, how many were cleared because a field no longer exists, and how many relationship transfers were re-bound or left unchanged. The message is raised as a warning rather than a success when anything could not be matched exactly, so nothing is dropped silently.

Source context​

On the Migrate Data screen the source is fixed by the screen you came from - it is the table whose records you are exporting. If a bundle was built for a different source data source or source table, Cortex warns you before continuing (Source data source differs), and re-matches the source field and relationship mappings against the current source where possible.

Importing from the Migration configurations page​

There, both the source and the target are resolved from the bundle. If a saved configuration already exists for the resolved source data source and table, Cortex confirms before replacing it, and any re-binding notes are shown before the Migrate Data screen opens pre-loaded for review. Nothing is saved until you click Save.

Building a bundle file outside Cortex​

Bundle files are XML, and importing an edited file is the supported way to prepare a large mapping set without clicking through the grid: export a bundle, generate or bulk-edit it with a script, then import it back.

  • Element names match the fields they populate, so a whole translations block - a LookupTranslations element with repeated LookupTranslationPair entries - can be inserted as one piece rather than row by row.
  • Elements this version of Cortex does not recognise are skipped rather than treated as an error, and they are named back to you with their line numbers (up to ten, plus a count of any others). Check those names if part of a mapping did not import - a mistyped element name is otherwise an invisible way to lose a value you entered by hand.
  • Malformed XML - an unclosed tag, a wrong root element - still fails, and Cortex reports the actual reason rather than a generic one.

See also​