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.

Object Migration Strategy Advanced Matching
Acct/Dept Match Only No
Article Match Only No
Asset/CI Match Only Yes: BEID, AppID, External ID, Service Tag (Asset only)
Asset Status Match Only No
Custom Attribute  Match And Merge No
Custom Attribute Choice Match And Merge No
Custom Attribute Section Match And Merge No
Custom Attribute Dependency Match And Merge No
Custom Attribute Value Match And Merge Yes: Attribute ID, Component ID, Item ID
Expense Account Match And Merge No
Form Match And Merge No
Group Match Only Yes: BEID, Name
Location Match Only Yes: BEID, External ID, Name
Location Room Match Only Yes: Parent Location, External ID, Name
Urgency, Impact, and Priority Match And Merge No
Product Type Match Only No
Product Model Match Only No
Project Classification Match And Merge No
Project Type Match And Merge No
Project Section Match Only Yes: BEID, Name
Recurring Schedule Match Only No
SLA/SLA Escalation Match And Merge No
Service Category Match And Merge No
Service/Service Offering  Match And Merge No
Standard Attribute Match Only Yes: Name
Tag Match And Merge Yes: BEID, Name
Ticket Approval Workflow Match And Merge No
Ticket Classification Match Only Yes: BEID, AppID, Component ID (aka “System Type”)
Ticket Source Match And Merge No
Ticket Status Match And Add Yes: BEID, AppID, Name, StatusType
Ticket Task Template Match Only No
Ticket Type Match And Merge No
Time Type Match And Merge No
Type Category Match And Merge No
User Match Only Yes: BEID, Name, AuthProvider, ExternalID, PrimaryEmail
Web Service Account Match And Merge No
Web Service Method
Note: Web Service Methods will be partly migrated as the configuration details are encrypted and cannot be exported.
Match And Merge
 
No
Web Service Provider Match And Merge No
Workflow Stage Match And Merge No
Workspace Match Only Yes: BEID Name

 

100% helpful - 2 reviews

Details

Article ID: 138969
Created
Tue 10/26/21 5:11 PM
Modified
Tue 7/5/22 10:24 AM