> 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/import-api/import-commands/importing-complex-relations.md).

# Importing complex relations

## Command structure

```json
[
  {
    "resourceType": "Complex Relation",
    "identifier": {
      "externalSystemId": "EXT_SYSTEM",
      "externalEntityId": "Asset_1234"
    },
    "complexRelationType": {
      "name": "Field Mapping"
    },
    "attributes": {
      "Original Column Name": [
        {
          "value": "XXX_COLUMN_1"
        }
      ],
      "00000000-0000-0000-0001-000500000011": [
        {
          "value": "True"
        }
      ]
    },
    "relations": {
      "00000000-0000-0000-0000-000000007088:TARGET": [
        {
          "name": "Asset 2",
          "domain": {
            "name": "Data Asset Domain 1",
            "community": {
              "name": "Data Community"
            }
          }
        }
      ],
      "00000000-0000-0000-0000-000000007089:TARGET": [
        {
          "name": "Table representation Asset",
          "domain": {
            "name": "Business Asset Domain 2",
            "community": {
              "name": "Business Community"
            }
          }
        }
      ]
    }
  }
]
```

## Identifier

The identifier for a complex relation may contain any of the following fields:

* `id`
* `externalSystemId` and `externalEntityId`
* `RELATION_TYPE_ID:RELATION_DIRECTION`

  <div data-gb-custom-block data-tag="hint" data-style="warning" class="hint hint-warning"><p>The list of relations, also known as complex relation legs, does not guarantee the unique identification of a complex relation. This method is prone to error in cases where there are two complex relations in Collibra:</p><ul><li>One complex relation with legs A, B and C.</li><li>Another complex relation with legs A, B, C and D.</li></ul><p>In this example, identifying a complex relation by the legs A, B and C results in an error because the API cannot determine which of the two complex relations it should process. In cases like this, use one of the other identification methods.</p></div>

{% hint style="info" %}
Code snippets in this section may show redundant data to demonstrate the fields accepted by the import API.
{% endhint %}

### Identifier structure

```json
{
  "id": "12345678-1234-1234-1234-123456788765"
}
```

```json
{
  "relations": {
    "00000000-0000-0000-0000-000000007088:TARGET": [
      {
        "name": "Data Element Source Asset 1",
        "domain": {
          "name": "Data Domain 1",
          "community": {
            "name": "The Community"
          }
        }
      },
      {
        "name": "Data Element Source Asset 2",
        "domain": {
          "name": "Data Domain 1",
          "community": {
            "name": "The Community"
          }
        }
      }
    ],
    "00000000-0000-0000-0000-000000007089:TARGET": [
      {
        "name": "Data Element Target Asset 1",
        "domain": {
          "name": "Data Domain 2",
          "community": {
            "name": "The Community"
          }
        }
      },
      {
        "name": "Data Element Target Asset 2",
        "domain": {
          "name": "Data Domain 2",
          "community": {
            "name": "The Community"
          }
        }
      }
    ],
    "00000000-0000-0000-0000-000000007090:TARGET": [
      {
        "name": "Mapping Specs 1",
        "domain": {
          "name": "Mapping Specs Domain",
          "community": {
            "name": "The Community"
          }
        }
      }
    ]
  }
}
```

```json
{
  "externalSystemId": "EXT_SYSTEM",
  "externalEntityId": "Asset_1234"
}
```

## Optional fields

| Field name          | Field type                                   | Remarks                                                                                                                      |
| ------------------- | -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| attributes          | `ATTRIBUTE_TYPE_ID` or `ATTRIBUTE_TYPE_NAME` | Sets or updates the complex relation attributes.                                                                             |
| complexRelationType | `id` or `name`                               | Sets the complex relation type. Should only be used for `create` operations. It is silently ignored for `update` operations. |
| relations           | `RELATION_TYPE_ID:RELATION_DIRECTION`        | Sets or updates the relations of the complex relation based on the relation type id and the direction.                       |

## Expected behavior

The behavior is similar to the commands for communities and domains.

## Add operation

If the complex relation needs to be created, the following fields have to be provided in order to import successfully:

* `relations`