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": {
    "name": "Sample Domain Name",
    "community": {
      "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 the final list of asset relations for each provided relation type and direction. With the default relationsAction=REPLACE, existing relations for the imported asset that are not listed are removed.
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

Importing 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"
        }
      }
    }
  ]
}

Every relation has a source asset and a target asset. The imported asset is the anchor asset. The :SOURCE and :TARGET suffixes show which end of the relation the listed assets occupy.

Suffix	Meaning
:TARGET	The listed assets are the targets. The input asset is the source.
:SOURCE	The listed assets are the sources. The input asset is the target.

Use a direction suffix when the source and target asset types are the same. Otherwise, the API cannot determine which end the listed assets occupy. For example, when a Business Asset is related to another Business Asset, add a suffix such as PUBLIC_ID:BusinessAssetGroupsBusinessAsset:SOURCE.

You can specify relation types in multiple ways:

• Use the relation type resource ID and the relation direction, such as 00000000-0000-0000-0000-000000007042:TARGET.

• Use the relation type public ID and the relation direction, such as PUBLIC_ID:ColumnIsPartOfTable:TARGET.

• Use the fully qualified relation type name and the relation direction, such as Column:is part of:contains:Table:TARGET.

Fully qualified relation type names cannot contain colons.

With the default relationsAction=REPLACE, the list of related assets is the complete final set for one anchor asset and one relation type. Existing relations in that scope that are not in the list are deleted.

The anchor asset depends on the direction:

• For :TARGET, the input asset is the source asset. The source asset is the anchor asset.

• For :SOURCE, the input asset is the target asset. The target asset is the anchor asset.

For the anchor asset, the Import API compares the listed assets with the existing relations of that relation type and direction:

• Matching relations are left unchanged.

• Existing relations that are not listed are deleted.

• Listed relations that do not exist are created.

The replace scope is determined only by the anchor asset and the relation type. It is not limited to the relations you created, the command that created them, or the direction suffix you used.

Relations of the same type belong to the same replace scope when they resolve to the same anchor asset, even if:

• They point to different related assets.

• They are declared from different assets or commands.

• One is declared with :SOURCE and the other with :TARGET.

As a result, importing one relation with the REPLACE action can delete another relation of the same type if that relation is not in the same list.

Example

Suppose Table_A already has two ColumnIsPartOfTable relations:

• Table_A → Column_1

• Table_A → Column_2

If you import ColumnIsPartOfTable:TARGET on Table_A with only [Column_1], the relation Table_A → Column_2 is deleted because Column_2 is not in the list.

If you split the two columns across two commands in the same import, each command evaluates the full existing set for Table_A independently. The [Column_1] command marks Table_A → Column_2 for deletion. The [Column_2] command marks Table_A → Column_1 for deletion. Both relations are then deleted.

To avoid deleting relations unintentionally:

• Declare the full set in one command. List all related assets for the anchor asset and relation type together.

• Use ADD_OR_IGNORE. Set relationsAction to ADD_OR_IGNORE if you only want to create missing relations.

To add relations without deleting existing ones, set relationsAction to ADD_OR_IGNORE.

With the REPLACE action, an empty list deletes all existing relations of that type for the anchor asset.

Importing 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"
}

You can also use a shorter syntax:

[
  "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"]
}

You can also use a shorter syntax:

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

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

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