Migration import logic

Migrating data between Collibra environments requires careful consideration of how objects are handled during the import process. This document outlines the core migration import logic, focusing on object matching using IDs and logical keys. You learn how Collibra determines whether to create new objects, update existing ones, or skip objects during migration, and how this process impacts your data.

Import matching

During import, Collibra tries to match each migrated object with an object in the target environment. 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, because the object is new to the source environment for example, the matching algorithm tries to use a logical key. This logical key may be different depending on the type of object.

Tip 

In most cases, the logical key is the name of the 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 never deletes objects, but it may reduce assignments, rename assets, or perform other modifications.

The table below describes the general import logic:

Outcome

When

Description

A matched object is not edited.

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.

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 in addition to the matched object.

In the target environment, another object has the same name as the matched object.

The matched object is edited with the properties from the migrated object, including the name.

The name of the unmatched object is changed to <original_name>-migration-YYYYMMDD_hhmmss.

Example 

The archive contains an asset type AWS Crawler with the ID 0000.

The target environment contains two asset types:

  • Crawler with the ID 0000.
  • AWS Crawler with the ID 1111.

Since there is a match on ID, after the import, the target environment contains the following updated assets:

  • AWS Crawler with the ID 0000.
  • AWS Crawler-migration-20250415_153605 with the 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 the objects are imported in the target environment. The table below provides 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

If there is a match on either the ID or the logical key, the asset is updated. Otherwise a new asset is created.

Note You cannot migrate assets that belong to system-owned domains, such as the Issues domains.

Asset type

 

Matching logic based on:

  1. ID
  2. Public ID
  3. Name

The following table contains the possible cases and results.

Case

Matched asset type 1

Matched asset type 2

Result
1

Any of:

  • ID
  • Public ID
  • Name
 N/A

Matched asset type 1 is updated.
3

Any of:

  • ID
  • Public ID
 Name

Matched asset type 1 is updated.

Matched asset type 2 is renamed.
5 ID Public ID

Migration fails because it tries to update asset type 1 with the same public ID as asset type 2.
11 None 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 fails. 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

If there is a match on either the ID or the logical key, the assignment is updated. Otherwise 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

If there is a match on either the ID or the logical key, the attribute is updated. Otherwise a new attribute is created.

Note 
  • You cannot migrate attributes that belong to system-owned domains, such as the Issues domains.
  • 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 and kind
  2. Public ID and kind
  3. Name and kind

Whenever the kind does not match, as a result of APIs deleting and recreating attribute types, a new attribute type is created while existing attribute types with the same name are renamed.

Assuming a match in kind, the following table contains the possible cases and results.

Case

Matched attribute type 1

Matched attribute type 2

Result
1

Any of:

  • ID
  • Public ID
  • Name
 N/A

Matched attribute type 1 is updated.
3

Any of:

  • ID
  • Public ID
 Name

Matched attribute type 1 is updated.

Matched attribute type 2 is renamed.
5 ID Public ID

Migration fails because it tries to update attribute type 1 with the same public ID as attribute type 2.
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 potential issues by deleting attribute types in the target environment before importing the archive.
Community

 

 Matching logic based on:
  1. ID
  2. Name

If there is a match on either the ID or the logical key, the asset is updated. Otherwise a new asset is created.

Note Communities are imported using the depth-first order.

Complex relation type

 

Matching logic based on:

  1. ID
  2. Public ID
  3. Name

The following table contains the possible cases and results.

Case

Matched complex relation type 1

Matched complex relation type 2

Result
1

Any of:

  • ID
  • Public ID
  • Name
 N/A

Matched complex relation type 1 is updated.
3

Any of:

  • ID
  • Public ID
 Name

Matched complex relation type 1 is updated.

Matched complex relation type 2 is renamed.
5 ID Public ID

Migration fails because it tries to update complex relation type 1 with the same public ID as complex relation type 2.
11 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
  2. Public ID
  3. Name

The following table contains the possible cases and results.

Case

Matched data quality rule 1

Matched data quality rule 2

Result
1

Any of:

  • ID
  • Public ID
  • Name
 N/A

Matched data quality rule 1 is updated.
3

Any of:

  • ID
  • Public ID
 Name

Matched data quality rule 1 is updated.

Matched data quality rule 2 is renamed.
5 ID Public ID

Migration fails because it tries to update data quality rule 1 with the same public ID as data quality rule 2.
11 None N/A

A new data quality rule is created.

Domain

Matching logic based on:

  1. ID
  2. Name and parent community

If there is a match on either the ID or the logical key, the community is updated. Otherwise a new community is created.

Note You cannot migrate Issues domains.

Domain type

Matching logic based on:

  1. ID
  2. Public ID
  3. Name

The following table contains the possible cases and results.

Case

Matched domain type 1

Matched domain type 2

Result
1

Any of:

  • ID
  • Public ID
  • Name
 N/A

Matched domain type 1 is updated.
3

Any of:

  • ID
  • Public ID
 Name

Matched domain type 1 is updated.

Matched domain type 2 is renamed.
5 ID Public ID

Migration fails because it tries to update domain type 1 with the same public ID as domain type 2.
11 None 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
  2. Public ID
  3. 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

Any of:

  • ID
  • Public ID
  • Source asset type, target asset type, role, and co-role

N/A

Matched relation type 1 is updated.
2

Any of:

  • ID
  • Public ID
 Source asset type, target asset type, role, and co-role

Matched relation type 2 is updated.
3 ID

Public ID

Migration fails because it tries to update relation type 1 with the same public ID as relation type 2.
4

None

N/A

A new relation type is created.

 

Roles

Matching logic based on:

  1. ID
  2. Public ID
  3. Name

The following table contains the possible cases and results.

Case

Matched role 1

Matched role 2

Result
1

Any of:

  • ID
  • Public ID
  • Name
 N/A

Matched role 1 is updated.
3

Any of:

  • ID
  • Public ID
 Name

Matched role 1 is updated.

Matched role 2 is renamed.
5 ID Public ID

Migration fails because it tries to update role 1 with the same public ID as role 2.
11 None N/A

A new role is created.

Scope

Matching logic based on:

  1. ID
  2. Public ID
  3. Name

The following table contains the possible cases and results.

Case

Matched scope 1

Matched scope 2

Result
1

Any of:

  • ID
  • Public ID
  • Name
 N/A

Matched scope 1 is updated.
3

Any of:

  • ID
  • Public ID
 Name

Matched scope 1 is updated.

Matched scope 2 is renamed.
5 ID Public ID

Migration fails because it tries to update scope 1 with the same public ID as scope 2.
11 None N/A

A new scope is created.

Note The global scope cannot be migrated.

Status

Matching logic based on:

  1. ID
  2. Public ID
  3. Name

The following table contains the possible cases and results.

Case

Matched status 1

Matched status 2

Result
1

Any of:

  • ID
  • Public ID
  • Name
 N/A

Matched status 1 is updated.
3

Any of:

  • ID
  • Public ID
 Name

Matched status 1 is updated.

Matched status 2 is renamed.
5 ID Public ID

Migration fails because it tries to update status 1 with the same public ID as status 2.
11 None N/A

A new status is created.

Validation rule

Matching logic based on:

  1. ID
  2. Full name and parent domain

If there is a match on either the ID or the logical key, the validation rule is updated. Otherwise 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

If there is a match on either the ID or the logical key, the asset view is updated. Otherwise a new asset view is created.
Dashboard

Matching logic based on:

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

If there is a match on either the ID or the logical key, the dashboard is updated. Otherwise a new dashboard is created.

The following table contains the possible cases and results.
Diagram view

Matching logic based on:

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

If there is a match on either the ID or the logical key, the diagram view is updated. Otherwise a new diagram view is created.
Search filter

Matching logic based on:

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

If there is a match on either the ID or the logical key, the search filter is updated. Otherwise a new search filter is created.