> For the complete documentation index, see [llms.txt](https://developer.collibra.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.collibra.com/api/guides/working-with-the-import-api-v2/import-commands.md).

# 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. | <p><code>id</code>, <code>name</code>, <code>externalSystemId</code> and <code>externalEntityId</code></p><p>See the topics of this section for examples of parameters that identify each resource.</p> |

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`             |
| <ul><li>Attributes</li></ul>                         | `SET`               |
| <ul><li>Relations</li></ul>                          | `SET`               |
| <ul><li>Tags</li></ul>                               | `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.

  <div data-gb-custom-block data-tag="hint" data-style="danger" class="hint hint-danger"><p>The long versions of these identifiers, <code>**external**SystemId</code> and <code>**external**EntityId</code>, replace the short versions <code>**ext**SystemId</code> and <code>**ext**EntityId</code>, which are deprecated.</p></div>

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

{% hint style="success" %}
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.
{% endhint %}

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.

{% hint style="warning" %}
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.
{% endhint %}

{% hint style="info" %}
For consistent results, use one import command per unique identifier.
{% endhint %}

## Space handling

The Import API does not remove any leading, trailing spaces, or zero-width Unicode characters from the name, description, or attribute values. When importing a relation, for example, specify the referenced asset name with all existing spaces.

The only exception to this rule is parsing attributes with multiple values, where spaces between values are removed. For example, the attribute string `Value A, Value B, Value C` produces the attribute values `Value A`, `Value B`, and `Value C`.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developer.collibra.com/api/guides/working-with-the-import-api-v2/import-commands.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.