Import commands

Each import command contains mandatory and optional fields.

Mandatory fields

The common mandatory fields for all command types are:

Field

Description

Example
resourceType The type of resource the import command is for. Community, Domain, Asset, Mapping, Complex Relation
identifier The universally unique identifier (UUID) of the resource or a combination of other characteristics that uniquely identify the resource.

id, name, externalSystemId and externalEntityId

See the topics of this section for examples of parameters that identify each resource.

For the optional fields, consider providing at least the minimum information required to create a new resource in Collibra if that resource needs to be created. For these fields, the default operation is SET/REPLACE.

Resource types

The following resources are supported for import or synchronization via the Import API. Depending on the resource type, the Import API performs one of two operations: SET/REPLACE or MERGE.

Resource Default operation
Communities MERGE
Domains MERGE
Assets and the following asset characteristics: MERGE
  • Attributes
 SET/REPLACE
  • Relation
 SET/REPLACE
  • Tags
 SET/REPLACE
Complex relations MERGE
Mappings MERGE

The MERGE operation

For MERGE operations:

  • If the resource does not exist, it is created with all the properties provided in the input.
  • If the resource exists, it is updated so that its properties match the ones provided in the input.

The SET/REPLACE operation

For SET/REPLACE operations:

  • If the resource exists with the same properties as defined in the input, no action is performed.
  • If the resource exists with properties other than the ones defined in the input, the resource is replaced with the one provided in the input.
  • If the resource does not exist, it is created.

Identifiers

Identifiers ensure the imported resource is uniquely identified. You must identify each resource by exactly one of the following:

  • id: the universally unique identifier (UUID) of the resource.
  • name: the community name, the domain and community names or the asset, domain and community names.
  • externalSystemId and externalEntityId: the IDs of the external system containing the resource ad the external resource.

    Warning extSystemId and extEntityId are deprecated.

Identifiers are mandatory properties in the JSON import commands and in the CSV and Excel templates.

Tip Keep the identifiers consistent to avoid possible performance drawbacks. It is possible but not recommended to use different identifiers for the same resource in the same input, for example, once name and once ID.

The identifiers from all of the commands of the import process, including the nested identifiers, are used in the identifier resolving stage of the import to:

  • Check if the resources exists.
  • Get the UUIDs of the resources.