The importance of IDs
When migrating configuration between Catalyst builds, matching internal IDs help the system preserve relationships and identify which configuration objects need to be created, updated or removed. Conflicting IDs can cause a migration to fail and may put live record data at risk.
How migration uses IDs
For configuration objects managed by ID, the migration process compares the Source and Target builds:
| ID comparison | Action in the Target build |
|---|---|
| The ID exists in the Source but not in the Target. | Create the object in the Target. |
| The ID exists in the Target but not in the Source. | Remove the object from the Target. |
| The ID exists in both builds. | Update the Target object from the Source, provided there is no conflict. |
These rules describe the ID-based migration of configuration objects. Some configuration items have specific exceptions—for example, user groups are matched by name, as described in Before you perform a migration.
Why matching IDs matters
An ID identifies an object and can also be used by other objects to refer to it. For example, an Object Class field may reference an Object Class with ID 1.
For that relationship to remain valid after migration, ID 1 must refer to the same Object Class in both Source and Target builds. Matching names alone are not enough.
Keeping IDs consistent helps prevent broken references, integrity errors and accidental changes to the configuration used by live records.
Conflicts that cause a migration to fail
An object has the same name but a different ID
Suppose an Object Class field has the same name in the Source and Target builds but was created independently, so it has a different internal ID.
To align the Target with the Source, migration would attempt to remove the Target field and recreate it with the Source field's ID. If existing Object Records contain data in that field, removing it could delete the associated field data.
The migration fails where that operation could cause data loss.
Field aliases match but field IDs differ
A migration also fails when the field aliases match but the field IDs do not.
This frequently occurs when someone creates a field directly in a Target build instead of creating it in the Source build and promoting it through migration.
What to do if you identify a conflict
The intended approach is to remove conflicting configuration from the Target build so the correct configuration can be migrated from the Source build.
Do not delete a Target field containing live data without first considering how that data will be preserved. Where a conflicting Target field holds data, it may be necessary to export the data before migration and import it again after the migration completes.
If you are unsure whether the Source and Target builds have a compatible configuration history, contact Autologyx before starting the migration.
Best practice for maintaining consistent IDs
- Create and test configuration in the agreed Source build.
- Promote configuration through the agreed sequence of builds, rather than recreating it independently in multiple environments.
- Avoid creating Object Classes or fields directly in a downstream Target build when they should be migrated from the Source.
- Review potential field ID and alias conflicts before promoting configuration to an environment that contains live records.
- Confirm any remediation or data export/import approach with Autologyx when data could be affected.
Useful info
- See Before you perform a migration for the configuration items that migrate and the special rules for user groups.
- Follow the pre-migration checklist before starting a migration.