> 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-domains.md).

# Importing domains

## Command structure

```json
[
  {
    "resourceType": "Domain",
    "identifier": {
      "name": "Technical Domain 1",
      "community": {
        "name": "Technical Community"
      }
    },
    "community": {
      "name": "Technical Community 2"
    },
    "description": "The Technical Domain is container for all technical assets of category 1.",
    "type": {
      "name": "Data Asset Domain"
    },
    "name": "Technical Domain 2",
    "responsibilities": {
      "00000000-0000-0000-0000-000000005018": [
        {
          "user": {
            "id": "00000000-0000-0000-0000-000000900001"
          }
        }
      ],
      "Business Steward": [
        {
          "userGroup": {
            "id": "00000000-0000-0000-0000-000001000002"
          }
        }
      ]
    }
  }
]
```

## Identifier

You can use any of the following fields as the identifier for a domain but only one at a time:

* `id`
* `name` and `community` identified by `id` or by `name`
* `externalSystemId` and `externalEntityId`

{% hint style="info" %}

* The `community` field has the same structure and requirements as the community identifier.
* 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
{
  "name": "Sample Domain Name",
  "community": {
    "name": "Sample Community Name"
  }
}
```

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

## Optional fields

| Field name                            | Field type                                              | Remarks                                                             |
| ------------------------------------- | ------------------------------------------------------- | ------------------------------------------------------------------- |
| description                           | String                                                  | Sets the domain description.                                        |
| type                                  | `id`, `name`, or `publicId`                             | Sets the domain type.                                               |
| community                             | The identifier of a community.                          | Moves the domain to the community. Should only be used for updates. |
| name                                  | String                                                  | Sets the domain name. Should only be used for updates.              |
| [responsibilities](#responsibilities) | The resource role and one or more users or user groups. | Creates or replaces responsibilities for the associated community.  |

## Expected behavior

If a domain with the name *Technical Domain 1* does not exist in the *Technical Community* community, the Import API performs an `insert` operation. It creates a domain with the specified name, description and of the specified type. The domain type is also set according to the specification.

{% hint style="info" %}
The domain name is changed to *Technical Domain 2* and the domain is moved to the *New Technical Community 2* because of the implicit `SET` operation. If the target community does not exist, the import results in an error.

If a domain named *Technical Domain 1* already exists, an `update` operation is performed. The community, description and domain type are updated based on the provided input.
{% endhint %}

## Add operation

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

* `name`
* `type`
* `community`

## Responsibilities

You define a responsibility by specifying a resource role, identified by name or ID, and assigning to it one or more users or user groups, identified by ID:

```json
{
  "00000000-0000-0000-0000-000000005018": [
    {
      "user": {
        "id": "00000000-0000-0000-0000-000000900001"
      }
    }
  ],
  "Business Steward": [
    {
      "userGroup": {
        "id": "00000000-0000-0000-0000-000001000002"
      }
    }
  ]
}
```

{% hint style="info" %}
The resource roles, users and user groups that define the imported responsibilities must already exist in Collibra.
{% endhint %}

You must specify each role only once in the list of responsibilities.

You can assign multiple users and multiple user groups to the same role:

```json
"responsibilities": {
  "Chief Data Officer": [
    {
      "user": {
        "id": "00000000-0000-0000-0000-000000900001"
      }
    },
    {
      "user": {
        "id": "00000000-0000-0000-0000-000000900002"
      }
    },
    {
      "userGroup": {
        "id": "00000000-0000-0000-0000-000001000002"
      }
    }
  ]
}
```

The Import API performs a query for the responsibilities in Collibra and:

* If the same responsibilities exist, the Import API performs no action.
* If responsibilities other than the ones provided in the input exist, they remain unchanged.
* If a responsibility exists with the same role but different assignees, the Import API deletes the existing responsibility and replaces it with the one provided in the input.
* If the responsibilities do not exist, the Import API creates them.