Migration import logic

The import logic determines how migrated objects are matched to objects in the target environment, and what happens if a match is found.

Import matching

During import, Collibra tries to match each migrated object with an object in the target. In most cases, matching is done first based on the ID of the object. If the target environment does not have an object matching the ID, the matching algorithm tries to use a logical key. This logical key may be different depending of the type of object.

Tip 

In most cases, the logical key is the name field, within the same type of object. For others, it is usually a combination of properties, for example:

  • For relation types, the logical key is the combination of the source (head) asset type, the role, the co-role, and the target (tail) asset type.
  • For assignments, the logical key is the combination of the asset type ID and scope ID.

Outcome of importing an object

Depending on the similarity of the objects in the archive and the target environment, importing an archive may edit existing objects or create new ones.

Note Migration will never delete objects, but it may reduce assignments, rename assets, and so on.

The table below contains the general import logic.

Outcome

When

Description

A matched object is not edited.
  1. A match is found based on the matching logic.
  2. The matched object has the same properties as the migrated object.

If the migrated object and the object in the target environment have the same properties, nothing happens.

A matched object is edited.
  1. A match is found based on the matching logic.
  2. The matched object has different properties than the migrated object.

The matched object is edited with the properties from the migrated object. Migration will never delete objects, but it may reduce assignments, rename assets, and so on.

Example 
  • If you migrate an assignment that includes fewer characteristic types than in the target, Collibra removes those characteristic types from the assignments, but does not delete the actual characteristic types.
  • If you migrate a view with a filter on a community that has a different name in the target, Collibra renames the community in the target.

An unmatched object is updated.
  1. A match is found based on the ID of the objects, but they have different names.
  2. In the target environment, another object has the same name as the migrated object.
  1. The name of the existing object with the same name is changed to <original name>-Migration-YYYYMMDD hh:mm:ss.
  2. The matched object is edited with the properties from the migrated object, including the name.
Example 

Before the import:

  • The target environment contains an asset type with the following information: Name: Crawler, ID: 0000.
  • The target environment contains a second asset type with the following information: Name: AWS Crawler, ID: 1111.
  • The archive contains an asset type with the following information: Name: AWS Crawler, ID: 0000.

After the import:

  • The target environment contains an asset type with the following information: Name: AWS Crawler, ID: 0000.
  • The target environment contains a second asset type with the following information: Name: AWS Crawler-Migration-20210101 13:15:12, ID: 1111.

A new object is created.

No match is found.

A new object is created with all properties from the migrated object, including the ID.

Import logic by object

Depending on the migrated object, different fields and secondary objects are exported along with it. This also affects the matching logic when these objects are imported in the target environment. The table below gives further information about how primary and secondary objects are imported.

Tip 

Use these options to filter the rows of the table to your needs:

Object Import logic

Asset

 

Matching logic based on:

  1. ID
  2. Full name and parent domain

The following table contains the possible cases and results.

Case

Matched asset 1

Matched asset 2

Result
1 ID

n/a

Matched asset 1 is updated.
2 Full name and parent domain

n/a

Matched asset 1 is updated.
3

None

n/a

A new asset is created.

Note Assets in system-owned domains (for example Issues) cannot be migrated.

Asset type

 

Matching logic based on:

  1. ID, public ID, and name
  2. ID and public ID
  3. ID and name
  4. Public ID and name
  5. ID
  6. Public ID
  7. Name

The following table contains the possible cases and results.

Case

Matched asset type 1

Matched asset type 2

Matched asset type 3

Result
1 ID, public ID, and name n/a

n/a

Matched asset type 1 is updated.
2 ID and public ID n/a n/a

Matched asset type 1 is updated.
3 ID and public ID Name n/a

Matched asset type 1 is updated.

Matched asset type 2 is renamed.
4 ID and name n/a

n/a

Matched asset type 1 is updated.
5 ID and name Public ID n/a

Migration fails because it tries to update both asset type 1 and asset type 2 with the same public ID, which must be unique.
6 ID Public ID

n/a

Migration fails because it tries to update both asset type 1 and asset type 2 with the same public ID, which must be unique.
7 ID

Public ID

Name

Migration fails because it tries to update both asset type 1 and asset type 2 with the same public ID, which must be unique.
8 ID Name n/a

Matched asset type 1 is updated.

Matched asset type 2 is renamed.
9 Public ID n/a n/a

Matched asset type 1 is updated.
10 Public ID Name n/a

Matched asset type 1 is updated.

The public ID of matched asset type 2 is renamed.
11 n/a n/a n/a

A new asset type is created.
Note 
  • If for an asset type, ratings are disabled in the archive file, but the matched asset type in the target environment has ratings enabled, the import will fail. This is because migration cannot delete the ratings of assets of that type.
  • Asset types are imported using the depth-first order.

Assignment

Matching logic based on:

  1. ID
  2. Asset type and scope

The following table contains the possible cases and results.

Case

Matched assignment 1

Matched assignment 2

Result
1

ID

n/a

Matched assignment 1 is updated.
2 Asset type and scope

n/a

Matched assignment 1 is updated.
3

None

n/a

A new assignment is created.

Note Assignments are imported in a specific order:

  1. Global assignments
  2. Scoped assignments
Attribute

 

Matching logic based on:

  1. ID
  2. Combination of parent asset, attribute type and value

The following table contains the possible cases and results.

Case

Matched object 1

Matched object 2

Result
1 ID

n/a

Matched object 1 is updated.
2 Combination of parent asset, attribute type and value

n/a

Matched object 1 is updated.
3

None

n/a

A new object is created.
Note 
  • Attributes in system-owned domains (for example Issues) cannot be migrated.
  • The only fields that you can migrate are validation scripts of validation rule assets and description fields of any resource.

Attribute type

 

Matching logic based on:

  1. ID, name and kind
  2. Name and kind
  3. ID and kind

The following table contains the possible cases and results.

Case

Matched attribute type 1

Matched attribute type 2

Result
1 ID, name and kind

n/a

Matched attribute type 1 is updated.

 
2 ID and name

n/a

Matched attribute type 1 is renamed.

A new attribute type is created.

Note 

Because you cannot edit the attribute type kind through Collibra's UI, this can only be done if:

  1. An attribute type is deleted.
  2. Using the Java/REST API, a new attribute type is created with the same name and ID as the deleted attribute type, but with a different kind.
3 Name

n/a

Matched attribute type 1 is renamed.

A new attribute type is created.
4 Name and kind

n/a

The ID of matched attribute type 1 is updated.
5

ID and kind

n/a

Matched attribute type 1 is renamed and updated.

6

ID

n/a

A new attribute type is created with a new ID.

Note 

Because you cannot edit the attribute type kind through Collibra's UI, this can only be done if:

  1. An attribute type is deleted.
  2. Using the Java/REST API, a new attribute type is created with the same name and ID as the deleted attribute type, but with a different kind.

7

ID and kind

Name and kind

Matched attribute type 2 is updated.

8

ID and kind

Name

Matched attribute type 1 is renamed and updated.

Matched attribute type 2 is renamed.

9

ID

Name and kind

Matched attribute type 2 is updated.

10

ID

Name

Matched attribute type 2 is renamed.

A new attribute type is created with a new ID.
11

None

n/a

A new attribute type is created.

Note If you import an attribute type of the kind Selection or Multiple Selection via the Solution install, allowed values from the CMA file are added to the list of allowed values in the target environment.

Tip If you know that fundamental changes were made to attribute types, you can avoid import problems by deleting attribute types in the target migration before importing the archive.
Community

 

Matching logic based on:

  1. ID, public ID, and name
  2. ID and public ID
  3. ID and name
  4. Public ID and name
  5. ID
  6. Public ID
  7. Name

The following table contains the possible cases and results.

Case

Matched community 1

Matched community 2

Matched community 3

Result
1 ID, public ID, and name n/a

n/a

Matched community 1 is updated.
2 ID and public ID n/a n/a

Matched community 1 is updated.
3 ID and public ID Name n/a

Matched community 1 is updated.

Matched community 2 is renamed.
4 ID and name n/a

n/a

Matched community 1 is updated.
5 ID and name Public ID n/a

Migration fails because it tries to update both community 1 and community 2 with the same public ID, which must be unique.
6 ID Public ID

n/a

Migration fails because it tries to update both community 1 and community 2 with the same public ID, which must be unique.
7 ID

Public ID

Name

Migration fails because it tries to update both community 1 and community 2 with the same public ID, which must be unique.
8 ID Name n/a

Matched community 1 is updated.

Matched community 2 is renamed.
9 Public ID n/a n/a

Matched community 1 is updated.
10 Public ID Name n/a

Matched community 1 is updated.

The public ID of matched community 2 is renamed.
11 n/a n/a n/a

A new community is created.

Note Communities are imported using the depth-first order.

Complex relation type

 

Matching logic based on:

  1. ID, public ID, and name
  2. Name
  3. ID

The following table contains the possible cases and results.

Case

Matched complex relation type 1

Matched complex relation type 2

Result
1

ID, public ID, and name

n/a

Matched complex relation type 1 is updated.
2 ID Name

Matched complex relation type 1 is updated.

Matched complex relation type 2 is renamed.
3 ID

n/a

Matched complex relation type 1 is updated.
4 Name

n/a

Matched complex relation type 1 is updated.
5

None

n/a

A new complex relation type is created.
Note 
  • When a complex relation leg type has the same role, co-role and target asset type than an existing one in the matched complex relation type, the existing one will be updated, even when the ID is different. Adding a second relation type with the same properties would result in an error.
  • Updating the assignment of a complex relation type which impacts leg types and attribute types can remove a leg type if it is no longer included in the migration archive. If the leg type has instance data, the import will fail.
  • Migration does not update leg types when source, target, role, co-role are identical.

Data quality rule

Matching logic based on:

  1. ID, public ID, and name
  2. ID and public ID
  3. ID and name
  4. Public ID and name
  5. ID
  6. Public ID
  7. Name

The following table contains the possible cases and results.

Case

Matched data quality rule 1

Matched data quality rule 2

Matched data quality rule 3

Result
1 ID, public ID, and name n/a

n/a

Matched data quality rule 1 is updated.
2 ID and public ID n/a n/a

Matched data quality rule 1 is updated.
3 ID and public ID Name n/a

Matched data quality rule 1 is updated.

Matched data quality rule 2 is renamed.
4 ID and name n/a

n/a

Matched data quality rule 1 is updated.
5 ID and name Public ID n/a

Migration fails because it tries to update both data quality rule 1 and data quality rule 2 with the same public ID, which must be unique.
6 ID Public ID

n/a

Migration fails because it tries to update both data quality rule 1 and data quality rule 2 with the same public ID, which must be unique.
7 ID

Public ID

Name

Migration fails because it tries to update both data quality rule 1 and data quality rule 2 with the same public ID, which must be unique.
8 ID Name n/a

Matched data quality rule 1 is updated.

Matched data quality rule 2 is renamed.
9 Public ID n/a n/a

Matched data quality rule 1 is updated.
10 Public ID Name n/a

Matched data quality rule 1 is updated.

The public ID of matched data quality rule 2 is renamed.
11 n/a n/a n/a

A new data quality rule is created.

Domain

Matching logic based on:

  1. ID, public ID, and name
  2. Name and parent community
  3. ID

The following table contains the possible cases and results.

Case

Matched domain 1

Matched domain 2

Result
1

ID, public ID, and name

n/a

Matched domain 1 is updated.
2 ID Name and parent community

Matched domain 1 is updated.

Matched domain 2 is renamed.
3 Name and parent community

n/a

Matched domain 1 is updated.
4 ID

n/a

Matched domain 1 is updated.
5

None

n/a

A new domain is created.

Note Issue domains cannot be migrated

Domain type

Matching logic based on:

  1. ID, public ID, and name
  2. ID and public ID
  3. ID and name
  4. Public ID and name
  5. ID
  6. Public ID
  7. Name

The following table contains the possible cases and results.

Case

Matched domain type 1

Matched domain type 2

Matched domain type 3

Result
1 ID, public ID, and name n/a

n/a

Matched domain type 1 is updated.
2 ID and public ID n/a n/a

Matched domain type 1 is updated.
3 ID and public ID Name n/a

Matched domain type 1 is updated.

Matched domain type 2 is renamed.
4 ID and name n/a

n/a

Matched domain type 1 is updated.
5 ID and name Public ID n/a

Migration fails because it tries to update both domain type 1 and domain type 2 with the same public ID, which must be unique.
6 ID Public ID

n/a

Migration fails because it tries to update both domain type 1 and domain type 2 with the same public ID, which must be unique.
7 ID

Public ID

Name

Migration fails because it tries to update both domain type 1 and domain type 2 with the same public ID, which must be unique.
8 ID Name n/a

Matched domain type 1 is updated.

Matched domain type 2 is renamed.
9 Public ID n/a n/a

Matched domain type 1 is updated.
10 Public ID Name n/a

Matched domain type 1 is updated.

The public ID of matched domain type 2 is renamed.
11 n/a n/a n/a

A new domain type is created.

Note Domain types are imported using the depth-first order.

Relation type

Matching logic based on:

  1. ID, source asset type, and target asset type
  2. Source asset type, target asset type, role, and co-role

The following table contains the possible cases and results.

Case

Matched relation type 1

Matched relation type 2

Result
1

ID, source asset type, and target asset type

n/a

Matched relation type 1 is updated.
2 ID Source asset type, target asset type, role, and co-role

Matched relation type 2 is updated.
3 Source asset type, target asset type, role, and co-role

n/a

Matched relation type 1 is updated.
4

None

n/a

A new relation type is created.

 

Roles

Matching logic based on:

  1. ID, public ID, and name
  2. ID and public ID
  3. ID and name
  4. Public ID and name
  5. ID
  6. Public ID
  7. Name

The following table contains the possible cases and results.

Case

Matched role 1

Matched role 2

Matched role 3

Result
1 ID, public ID, and name n/a

n/a

Matched role 1 is updated.
2 ID and public ID n/a n/a

Matched role 1 is updated.
3 ID and public ID Name n/a

Matched role 1 is updated.

Matched role 2 is renamed.
4 ID and name n/a

n/a

Matched role 1 is updated.
5 ID and name Public ID n/a

Migration fails because it tries to update both role 1 and role 2 with the same public ID, which must be unique.
6 ID Public ID

n/a

Migration fails because it tries to update both role 1 and role 2 with the same public ID, which must be unique.
7 ID

Public ID

Name

Migration fails because it tries to update both role 1 and role 2 with the same public ID, which must be unique.
8 ID Name n/a

Matched role 1 is updated.

Matched role 2 is renamed.
9 Public ID n/a n/a

Matched role 1 is updated.
10 Public ID Name n/a

Matched role 1 is updated.

The public ID of matched role 2 is renamed.
11 n/a n/a n/a

A new role is created.

Scope

Matching logic based on:

  1. ID, public ID, and name
  2. ID and public ID
  3. ID and name
  4. Public ID and name
  5. ID
  6. Public ID
  7. Name

The following table contains the possible cases and results.

Case

Matched scope 1

Matched scope 2

Matched scope 3

Result
1 ID, public ID, and name n/a

n/a

Matched scope 1 is updated.
2 ID and public ID n/a n/a

Matched scope 1 is updated.
3 ID and public ID Name n/a

Matched scope 1 is updated.

Matched scope 2 is renamed.
4 ID and name n/a

n/a

Matched scope 1 is updated.
5 ID and name Public ID n/a

Migration fails because it tries to update both scope 1 and scope 2 with the same public ID, which must be unique.
6 ID Public ID

n/a

Migration fails because it tries to update both scope 1 and scope 2 with the same public ID, which must be unique.
7 ID

Public ID

Name

Migration fails because it tries to update both scope 1 and scope 2 with the same public ID, which must be unique.
8 ID Name n/a

Matched scope 1 is updated.

Matched scope 2 is renamed.
9 Public ID n/a n/a

Matched scope 1 is updated.
10 Public ID Name n/a

Matched scope 1 is updated.

The public ID of matched scope 2 is renamed.
11 n/a n/a n/a

A new scope is created.

Note The global scope cannot be migrated.

Status

Matching logic based on:

  1. ID, public ID, and name
  2. ID and public ID
  3. ID and name
  4. Public ID and name
  5. ID
  6. Public ID
  7. Name

The following table contains the possible cases and results.

Case

Matched status 1

Matched status 2

Matched status 3

Result
1 ID, public ID, and name n/a

n/a

Matched status 1 is updated.
2 ID and public ID n/a n/a

Matched status 1 is updated.
3 ID and public ID Name n/a

Matched status 1 is updated.

Matched status 2 is renamed.
4 ID and name n/a

n/a

Matched status 1 is updated.
5 ID and name Public ID n/a

Migration fails because it tries to update both status 1 and status 2 with the same public ID, which must be unique.
6 ID Public ID

n/a

Migration fails because it tries to update both status 1 and status 2 with the same public ID, which must be unique.
7 ID

Public ID

Name

Migration fails because it tries to update both status 1 and status 2 with the same public ID, which must be unique.
8 ID Name n/a

Matched status 1 is updated.

Matched status 2 is renamed.
9 Public ID n/a n/a

Matched status 1 is updated.
10 Public ID Name n/a

Matched status 1 is updated.

The public ID of matched status 2 is renamed.
11 n/a n/a n/a

A new status is created.

Validation rule

Matching logic based on:

  1. ID
  2. Full name and parent domain

The following table contains the possible cases and results.

Case

Matched validation rule 1

Matched validation rule 2

Result
1 ID

n/a

Matched validation rule 1 is updated.
2 Full name and parent domain

n/a

Matched validation rule 1 is updated.
3

None

n/a

A new validation rule is created.

Note If there is a match, only the Description and Validation script are changed. Other characteristics are not changed.
Workflow

Matching logic based on:

  1. Workflow process ID
  2. Workflow name

The following table contains the possible cases and results.

Case

Matched workflow 1

Matched workflow 2

Result
1

Process ID and workflow name

n/a

Matched workflow 1 is updated.
2 Process ID Workflow name

Matched workflow 1 is updated.

Matched workflow 2 is renamed with a suffix of - $processId.
3

None

n/a

A new workflow is created.

Navigation objects

 
Asset view

Matching logic based on:

  1. ID
  2. Name, type, location, and common assigned resources

The following table contains the possible cases and results.

Case

Matched asset view 1

Matched asset view 2

Result
1 ID

n/a

Matched asset view 1 is updated.
2 Name, type, location, and at least one common assigned resource

n/a

Matched asset view 1 is updated.
3

None

n/a

A new asset view is created.
Dashboard

Matching logic based on:

  1. ID
  2. Name, type, location, and common assigned resources

The following table contains the possible cases and results.

Case

Matched dashboard 1

Matched dashboard 2

Result
1 ID

n/a

Matched dashboard 1 is updated.
2 Name, type, location, and at least one common assigned resource

n/a

Matched dashboard 1 is updated.
3

None

n/a

A new dashboard is created.
Diagram view

Matching logic based on:

  1. ID
  2. Name, type, location, and common assigned resources

The following table contains the possible cases and results.

Case

Matched diagram view 1

Matched diagram view 2

Result
1 ID

n/a

Matched diagram view 1 is updated.
2 Name, type, location, and at least one common assigned resource

n/a

Matched diagram view 1 is updated.
3

None

n/a

A new diagram view is created.
Search filter

Matching logic based on:

  1. ID
  2. Name, type, location, and common assigned resources

The following table contains the possible cases and results.

Case

Matched search filter 1

Matched search filter 2

Result
1 ID

n/a

Matched search filter 1 is updated.
2 Name, type, location, and at least one common assigned resource

n/a

Matched search filter 1 is updated.
3

None

n/a

A new search filter is created.