Matching Rules for Configuration Copying

This article describes how the configuration import/export process will apply to the various objects in the system that can be migrated.

Migration Objects

Within the configuration migration system, each configurable item from the source environment is exported as a "migration object", which is then matched, created or updated in the destination environment. Each migration object has its own rules for how it is added to the destination environment. 

A migration object can be something complex that has other objects as subcomponents. For example, a Form can have child components of specific custom attribute definitions. 

When a migration object includes a relationship between two different things (such as a Ticket Type's associated Groups), the relationships are not "merged" but rather are added/deleted in the target environment so that they match what was configured in the source environment.  For example, if exported data has a Ticket Type that has one associated Group, and the same Ticket Type in the target database has associations with multiple Groups, the configuration migration will delete the relationships in the target database so it matches the desired state in the exported data.

It’s important to note that deleting “relationships” is the only case where the configuration migration will delete database records in the target database.

Migration Rules

Each migration object will be added to the new environment using one of the following rules:

Match Only

Match a source object to an existing target object only. Never add a new target object or update an existing target object. This is used for items like user records, which have their own way of being created and are expected to be the same or similar between the source and target environments. 

1. Match a source object to an existing target object based on ID (plus Advanced Matching Rules if applicable).
2. If an existing target object is found, use it for all references.
3. If an existing target object is not found, then:
   1. If all reference to this object are marked with an “Allow Blank If No Match” rule, then remove all references and do not migrate this object.  
   2. If not, Error – the import cannot be run.

Match And Add

Match a source object to an existing target object. Add a new target object if no match is found.  Never update an existing target object.

1. Match a source object to an existing target object based on ID (plus Advanced Matching Rules if applicable).
2. If an existing target object is found, use it for all references.
   1. If the existing target object is different than the source object, then add a “Warning” to the execution plan but do not update.
3. If an existing target object is not found, then add a new target object using the source object data.

Match And Merge

Match a source object to an existing target object. Add a new target object if no match is found.  Update update an existing target object if different than the source object

1. Match a source object to an existing target object based on ID (plus Advanced Matching Rules if applicable).
2. If an existing target object is found, use it for all references.
   1. If the existing target object is different than the source object, then update the target object using the source object data.
3. If an existing target object is not found, then add a new target object using the source object data.

In this case, if the IDs match but the created date indicates the object was created in the source environment after that environment had been copied from the destination environment, it will be treated as a non-match. This would indicate that by coincidence the IDs in two separate environments match but they probably don't represent the same record. 

Allow Blank If No Match

The “Allow Blank If No Match” rule can be applied to migration objects when no match can be found, and the migration rules don't allow creating a new record. This allows the import to remove the references to the object if it’s unable to find a match in the target database. 

This is used in the following cases:

• Workflow: Group, User and Variable Assignment (e.g. Service person-type custom attribute) references
• Workflow: Condition Step Filter and Argument references
• Ticket/Project Form: Default Value references
• Service: Maintenance Window references

Object Rules

The following describes the rules applied to each high-level Object.