Skip to main content
Version: 3.3

Checking Compatibility Before a Migration

A migration can fail one record at a time, hours in, on something that could have been found in advance - a source value with no translation, a translated value the target no longer offers, or an attachment the target will refuse. Check Migration Compatibility, under Utilities, looks for those problems before a real run, and can smoke-test a chosen slice of the data against the target's own business rules.

It uses the same saved migration configuration as the migration itself, so there is nothing extra to prepare beyond the mapping you would already have built - see Field Mappings and Mapping Bundles.

note

The page needs the Migration Configs admin permission on the Cortex security group - the same right that controls Utilities → Migration configurations. Like the rest of Migrate Data, it is included with the migration tooling in the Archive and Platform editions. See Post-upgrade Security Group Permissions.

Choosing what to check​

  1. Open Utilities → Check Migration Compatibility.
  2. Pick the Source data source - a data source Cortex can migrate from.
  3. Pick the Records to check:
    • Saved search - run one of the source's saved searches and check the records it returns.
    • All records in the table - check everything in the selected table.
    • First N records - check the first Number of records (up to 100,000), which is a quick way to sample a very large table.
  4. Pick the Table the records come from.
  5. If the table has no saved configuration yet, click Edit migration configuration to open the Migrate Data screen with the run action hidden, build or adjust the mapping, and save it. The page then loads that saved configuration for its checks.

The compatibility scan​

Click Run scan to walk the chosen records. The scan can be cancelled while it runs, and its findings are listed with the record, the issue, how serious it is, the field or file involved, and an explanation.

FindingWhat it means
Untranslated valueA source value matches no row in the value translations and the mapping has no default, so the raw source value would be forwarded to the target.
Invalid destination valueA translated value is not one of the target field's known choices.
Attachment over the per-file limitA single attachment is larger than the target's per-file size limit.
Attachment over the per-record limitThe record's attachments together exceed the target's per-record size limit.
Attachment check incompleteThe record's attachment list could not be read, so its attachments were not checked.
Attachment size unknownThe source does not report the size of an attachment, so it could not be checked.

Each finding is marked Warning - the migration can proceed, but the value may not arrive as intended - or Error, meaning the target is expected to reject the record or store an invalid value.

A checkbox labelled Validate translated values against the target field's choices controls the invalid destination value check. It is on by default; turn it off where the target's choice list cannot be resolved reliably, so the scan does not report translations that are in fact fine.

tip

Fix what the scan finds in the mapping itself - add a translation row or a default value for untranslated values, correct or re-point a translation for invalid destination values - then scan again before running the migration. See Value Translations.

The combination smoke test​

A scan checks values; a combination smoke test checks the target's rules. Choose a subset of mapped fields, and Cortex picks the records that exercise every value of those fields, sends them through the full migration - relationships and attachments included, exactly as the saved configuration describes - and reports what the target did with them.

  1. Under Combination smoke test, tick the fields to exercise. Each entry is named <target field> (from <source field>).
  2. Choose Values to exercise:
    • Values present in the dataset - the values actually held by the records being checked.
    • Every value the mappings can produce (translations, static and defaults) - including translated destinations and fixed values, so a mapping that no record happens to exercise yet is still tested.
  3. Choose Records to send:
    • Send every record in the selected dataset
    • Send one record per distinct combination of the selected fields' values
    • Send the smallest set that covers every value of every selected field
  4. Click Plan test records to see the records Cortex selected. Values or combinations no record in the dataset can cover are reported, so you know what the test could not reach.
  5. Click Run test to send them. The run is a real migration of those records, so it creates records in the target system.
caution

The smoke test writes to the target. Use it on a target you are willing to hold test records in, or run it before a bulk migration begins.

See also​