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.

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.

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.

When it comes to the command structure, you can identify directly assets and complex relations 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.

The only way to uniquely identify a complex relation 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.