Importing assets

Command structure
[
  {
    "resourceType": "Asset",
    "identifier": {
      "name": "Asset 1",
      "domain": {
        "name": "Business Data Domain 1",
        "community": {
          "name": "Data Community"
        }
      }
    },
    "domain": {
      "id": "43215678-1234-1234-1234-123456788765"
    },
    "name": "New Asset 1",
    "displayName": "A1",
    "type": {
      "name": "Column"
    },
    "attributes": {
      "Original Column Name": [
        {
          "value": "XXX_COLUMN_1"
        }
      ],
      "00000000-0000-0000-0001-000500000011": [
        {
          "value": "True"
        }
      ]
    },
    "relations": {
      "00000000-0000-0000-0000-000000007062:SOURCE": [
        {
          "name": "Asset 2",
          "domain": {
            "name": "Data Asset Domain 1",
            "community": {
              "name": "Data Community"
            }
          }
        }
      ],
      "00000000-0000-0000-0000-000000007038:SOURCE": [
        {
          "name": "Table representation Asset",
          "domain": {
            "name": "Business Asset Domain 2",
            "community": {
              "name": "Business Community"
            }
          }
        }
      ]
    },
    "status": {
      "name": "Accepted"
    },
    "tags": [
      "sample",
      "technical",
      "crucial"
    ],
    "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 an asset but only one at a time:

  • id
  • name and domain identified by id
  • name and domain identified by name and by community identified by id or by name
  • externalSystemId and externalEntityId
Identifier structure
{
  "id": "12345678-1234-1234-1234-123456788765",
  "name": "Sample Asset Name",
  "domain": {
    "id": "98765678-1234-1234-1234-123456788765",
    "name": "Sample Domain Name",
    "community": {
      "id": "43215678-1234-1234-1234-123456788765",
      "name": "Sample Community Name"
    }
  },
  "externalSystemId": "EXT_SYSTEM",
  "externalEntityId": "Asset_1234"
}
  • The community and domain fields have the same structure and requirements as the community and domain identifiers.
  • 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
type id, name, or publicId Updates the asset type.
attributes The attribute type and the value or an array of values. Sets or updates the asset attributes.
domain The identifier of a domain. Moves the asset to the domain. Should only be used for updates.
name String

Updates the asset full name. Should only be used for updates.

The full name must be unique per domain. For more details, see Asset names.

displayName String Sets or updates the asset display name. One domain may contain multiple assets with the same display name. If not specified, the display name will be the same as the name field
relations The relation type, the relation direction, and the identifier of the related asset. Sets or updates the asset relations based on the relation type ID and the direction.
responsibilities The resource role and one or more users or user groups. Creates or replaces responsibilities for the associated community.
status id or name Sets or updates the asset status.
tags A list of string values. Sets or deletes the asset tags. The operation does not add or update a list of tags.

Expected behavior

The behavior is similar to the import of communities and domains.

Add operation

If the asset needs to be created, the following fields must be provided in order to import successfully:

  • name
  • type
  • domain

Additional information

Relations

You define a relation by specifying the relation type, the relation direction and the identifier of the related asset:

"relations": {
  "00000000-0000-0000-0000-000000007030:SOURCE": [
    {
      "name": "Related Asset",
      "domain": {
        "name": "Sample Domain Name",
        "community": {
          "name": "Sample Community Name"
        }
      }
    }
  ]
}

You can specify relation types in multiple ways:

  • Using the relation type resource ID and the relation direction separated by a colon, for example: 00000000-0000-0000-0000-000000007042:TARGET.
  • Using the relation type public ID and the relation direction separated by a colon, for example: PUBLIC_ID:ColumnIsPartOfTable:TARGET.
  • Using a fully qualified relation type name separated by colons and the relation direction also separated by a colon, for example: Schema:contains:is part of:Table:SOURCE.

You can not use the fully qualified name to specify a relation type if the name of the relation type contains a colon.

The relation direction refers to the related asset:

  • SOURCE, when the related asset is the head of the relation.
  • TARGET, when the related asset is the tail of the relation.

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

  • If the same relations exist, the Import API performs no action.
  • If the list of relations is different from the one defined in the input, the Import API replaces or creates the relations that are provided in the input and performs no action on the other existing relations.
  • If the relations do not exist, the Import API creates them.
Attributes

You define attributes by specifying the attribute type and the attribute value or values.

When you provide an attribute, the import API performs a query for the attribute in Collibra.

  • If the same attributes exist, the Import API performs no action.
  • If the list of attributes is different from the one provided in the input exist, the Import API replaces or creates the attributes that are provided in the input and performs no action on the other existing attributes.
  • If multi-value attributes exist, the values provided in the input file are updated and the rest of the existing values are deleted.
  • If the attributes do not exist, the Import API creates them.

You can use any of the following methods to specify an attribute type but only one at a time:

  • The attribute type ID, for example "00000000-0000-0000-0000-000000003115".
  • The attribute type name, for example "Descriptive Example".
  • The attribute type public ID, for example "DescriptiveExample".

For each attribute type you can provide a list of attribute values.

For attribute types with one value, the structure is as follows:

{
  "value": "Some value"
}

Most attribute types in Collibra have one value.

For attribute types with multiple values, such as Multiple Selection attributes, the structure is as follows:

{
  "values": ["Some value 1", "Some value 2"]
}

To import multiple attributes of the same type, such as Descriptive Example attributes for an asset, the attributes field structure is as follows:

{
  ...
  "attributes": {
    "Descriptive Example": [
      {
        "value": "This is first descriptive example"
      },
      {
        "value": "This is second descriptive example"
      }
    ]
  }
  ...
}

Specifying both a value and a values field results in an error.

Responsibilities

You can enable or disable the ability to import responsibilities at asset level by configuring the Asset responsibilities support setting in Collibra Console.

Setting Description
Asset responsibilities support
  • True: Enable importing responsibilities at asset level.
  • False (default): Disable importing responsibilities at asset level.

When the setting is disabled and responsibilities are defined at asset level, you get an error.

Setting specific responsibilities on a large number of assets will affect the performance and stability of the system.

Define responsibilities on communities or domains so that the assets can automatically inherit those 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:

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

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:

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

When you provide tags in the input command, they replace any tags that the asset already has. After processing the import command for an asset, only the tags provided in the input are assigned. If you provide an empty tag list in the input, all tags are deleted from the asset.