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

# Importing communities

## Command structure

```json
[
  {
    "resourceType": "Community",
    "identifier": {
      "name": "Technical Community"
    },
    "description": "The Technical Community is organization gathering all technical domains of our company.",
    "name": "New Technical Community",
    "parent": {
      "name": "Parent of All Communities"
    },
    "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 community but only one at a time:

* `id`
* `name`
* `externalSystemId` and `externalEntityId`

### Identifier structure

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

```json
{
  "name": "Sample Community Name"
}
```

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

## Optional fields

| Field name                            | Field type                                              | Remarks                                                            |
| ------------------------------------- | ------------------------------------------------------- | ------------------------------------------------------------------ |
| description                           | String                                                  | Sets the community description.                                    |
| name                                  | String                                                  | Sets the community name. Should only be used for updates.          |
| parent                                | The identifier of a community.                          | Sets the parent community for the community.                       |
| [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 community with the name *Technical Community* does not exist, the import API performs an `insert` operation. It creates a community with the specified name and description. The parent community is retrieved and set as parent for the newly created community. If the parent community does not exist, the import results in an error.

{% hint style="info" %}
The community name is changed to *New Technical Community* because of the implicit `SET` operation.

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

The Import API does not support importing nested communities in a single request. Parent communities of imported communities must exist in Collibra for the imported communities to be created successfully. The following example is not supported: to import all three communities, you must send three requests, each with just one community, in the order of dependency, starting from root to the children.

```json
[
  {
    "name": "Technical Community 1",
    "resourceType": "Community",
    "identifier": {
      "externalEntityId": "externalEntity1",
      "externalSystemId": "externalSystem1"
    },
    "parent": {
      "name": "Parent of All Communities"
    }
  },
  {
    "name": "Technical Community 2",
    "resourceType": "Community",
    "identifier": {
      "externalEntityId": "externalEntity2",
      "externalSystemId": "externalSystem2"
    },
    "parent": {
      "name": "Technical Community 1"
    }
  },
  {
    "name": "Technical Community 3",
    "resourceType": "Community",
    "identifier": {
      "externalEntityId": "externalEntity3",
      "externalSystemId": "externalSystem3"
    },
    "parent": {
      "name": "Technical Community 2"
    }
  }
]
```

{% hint style="info" %}
Although not guaranteed, in some situations, the import may still be able to handle nested communities in a single request. To ensure consistency, you should avoid such requests.
{% endhint %}

## Add operation

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

* `name`

## 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.


---

# 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-communities.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.