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.

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 or MERGE.

Resource Performed operation
Communities MERGE
Domains MERGE
Assets and the following asset characteristics: MERGE
  • Attributes
 SET
  • Relations
 SET
  • Tags
 SET
Responsibilities for communities, domains and assets SET
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 operation

For SET operations:

  • If the resource exists with the same properties as defined in the input, the Import API performs no action.
  • If the resource exists with properties different from the ones defined in the input, the Import API replaces or creates the properties that are provided in the input and performs no action on the other existing properties.
  • If the resource exists with properties that have multiple values, for example multi-value attributes or tags, the values provided in the input file are updated and the rest of the existing values are deleted.
  • 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.

    The long versions of these identifiers, externalSystemId and externalEntityId, replace the short versions extSystemId and extEntityId, which are deprecated.

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

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.

Command merging

During the import process, multiple subsequent commands with the same identifier are merged and executed as a single import command. This means that an imported asset has attributes and relations from all merged commands.

Only commands that immediately follow each other can be merged, otherwise the last command in the file can override the results of the previous commands with the same identifier.

For consistent results, use one import command per unique identifier.