> 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/importing-mappings/external-mappings.md).

# External mappings

You can use external mappings to link external resources with Collibra resources. The external mapping is identified by a pair of properties, which you can choose freely as long as they uniquely identify a resource in the external system:

* **externalSystemId** with a maximum of 36 characters.
* **externalEntityId** with a maximum of 255 characters.

A good choice for **externalSystemId** is the name or identifier of the external system. Therefore, this property is typically common to a large number of mappings. Often, a specific import or synchronization process will only use a single **externalSystemId**, though it’s not a general rule as we can possibly have imports that ingest data originating from several external systems.

The **externalEntityId** is used to uniquely identify a resource in that external system identified by **externalSystemId**. If possible, use the same identifier that the external system uses to identify the resource as **externalEntityId**. However, there are cases where the resource you want to create does not have a specific identifier in the external system. In such a scenario, connect multiple identifiers from that external system to build a new identifier that is unique for that resource. One use case is using a complex relation in Collibra to identify a foreign key in a relational database. Foreign keys don’t necessarily have unique IDs in the database but you could concatenate the schema name, table name, column name and foreign key ID, for instance, to create a unique identifier.

{% hint style="success" %}
You can hash the **externalEntityId** value before inserting it in the import command if there is a risk that the resulting identifier exceeds the 255 characters limit. In practice, this ID is usually only used as input for import scripts, so it’s usually acceptable that its generation process be destructive. Note you cannot use this technique if the ID has to be used for any other purpose than to identify the Collibra resource.
{% endhint %}

Once you have defined a way to identify an external resource, you can associate it with a Collibra resource. An association with an asset or a complex relation is the most common use case, but you can also create an association with a domain or a community.

{% hint style="info" %}
When it comes to the command structure, you can identify directly [assets](/api/guides/working-with-the-import-api-v2/import-commands/importing-assets.md) and [complex relations](/api/guides/working-with-the-import-api-v2/import-commands/importing-complex-relations.md) by external mappings in their respective commands. The **externalSystemId** and **externalEntityId** pair is a valid way of specifying the identifier section for those resources. When you use this identification, an external mapping is created automatically if none is present yet, along with the associated resource. For that reason, explicit mapping commands as presented in this section are actually rarely used as a direct specification in the resource identifier is shorter and thus more efficient.
{% endhint %}

{% hint style="success" %}
The only way to uniquely identify a [complex relation](/api/guides/working-with-the-import-api-v2/import-commands/importing-complex-relations.md) in an import script is by using the complex relation ID or an external mapping. As the complex relation IDs are rarely known when building an import script, it’s actually the second option that is the more frequent.
{% endhint %}


---

# 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/importing-mappings/external-mappings.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.