Importing communities

Copy

Command structure

[
  {
    "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

The identifier for a community must contain any of the following fields:

  • id
  • name
  • externalSystemId and externalEntityId
Copy

Identifier structure

{
  "id": "12345678-1234-1234-1234-123456788765",
  "name": "Sample Community Name",
  "externalSystemId": "EXT_SYSTEM",
  "externalEntityId": "Community_1234"
}

Note Code snippets in this section may show redundant data to demonstrate the fields accepted by the import API.

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 Same as identifier for community. Sets the parent community for the community.
responsibilities RESOURCE_ROLE_ID or RESOURCE_ROLE_NAME 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.

Note 

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.

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:

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

Note The resource roles, users and user groups that define the imported responsibilities must already exist in Collibra.

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:

Copy
"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.