Skip to content

Identifiers

Warning

You are viewing documentation for an incubating feature. This feature is not yet fully supported and may change or be removed in future versions. If you are looking for information about the stable Batch API - click here.

Overview

The Batch API provides three different way to identify components and references in Ardoq. The first table shows which identifiers can be used for each operation, while the second table shows which fields the identifiers can be used as values for.

Type Operation Ardoq OID Unique By Batch Id
Component / Reference Create ❌ ❌ ✅
Component / Reference Update ✅ ✅ ❌
Component / Reference Upsert ❌ ✅ ❌
Component / Reference Delete ✅ ✅ ❌
Type Field Ardoq OID Unique By Batch Id
Component parent ✅ ✅ ✅
Reference source ✅ ✅ ✅
Reference target ✅ ✅ ✅

Ardoq OID

The Ardoq OID is a unique identifier for all components and references in Ardoq. This id is a unique string that is generated by Ardoq when an entity is created. The OID is immutable and will never change for the lifetime of the entity. The OID can always be used to identify components and references that exist in Ardoq.

Unique By

The Batch API allows you to identify both components and references in Ardoq using a Unique By identifier.

A Unique By identifier allows you to perform operations on an entity without knowing the Ardoq OID of the entity. This is particularly useful when you are working with components and references in Ardoq that correspond to entities that have a unique id in an external system.

A "Unique By" identifier may be used in a Batch request in any position where an Ardoq OID may be used. This means that not only can you update and delete both components and references using a "Unique By", it may also be used to identify a component in the parent field of another component or in the source or target field of a reference.

Important

A "Unique By" identifier is NOT global. It is used to identify a single entity in a workspace by the value of a custom field. Multiple entities with the same custom field and value may be present in different workspaces.

A "Unique By" identifier is a JSON object with the following structure: 

{
    "rootWorkspace": "65099b8a499b5d0001d84922",
    "customField": "my_custom_field",
    "value": "Some value"
}

The fields are all required. The following table describes the semantic meaning of each field:

Field Description Example 
rootWorkspace
 The Ardoq OID of the workspace that the component or reference belongs 
"65099b8a499b5d0001d84922"
 
customField
 The name of the custom field that has a value that uniquely identifies the entity in the workspace. The custom field must have the Ardoq type Text 
"my_field"
 
value
 The value of the custom field. As the field has the Text type the value must be a string. 
"My unique value"

Components

Components are a natural way to model "things" in an external system. For example, a component in Ardoq may represent a server in a data center, a user in an identity management system, or a product in a product catalog etc. As such, it is natural to use a custom field with a value that uniquely identifies the data in the external system. For example, if we were to model a Github repository in Ardoq we may add a custom field to the component that has the name github_id and a value that corresponds to the id of the repository in Github.

In order to use a Unique By identifier to identify a component, the following requirements must be met:

  1. The custom field should be defined for the component type. For example, if you wish to use a Unique By identifier to identify a component of type Server by the field my_id, then the custom field my_id must be defined for either all component types in the workspace identified by rootWorkspace or explicitly the Server type defined in the workspace identified by rootWorkspace.
  2. The custom field must be of type Text
  3. The value of the custom field must be unique for all components within the workspace identified by rootWorkspace.

References

Unlike components, references are used to model the relations between entities. These relationships rarely have a unique identifier in the external system. However, it is still possible to use a Unique By identifier to identify a reference in Ardoq. For example, if you have a reference between two components that represent a server and a user in an identity management system, you may add a custom field to the reference that has a value that uniquely identifies the reference in the external system.

In order to use a Unique By identifier to identify a reference, the following requirements must be met:

  1. The custom field should be defined for the reference type. For example, if you wish to use a Unique By identifier to identify a reference of type Belongs To by the field my_id, then the custom field my_id must be defined for either all reference types in the workspace identified by rootWorkspace or explicitly the Belongs To type defined in the workspace identified by rootWorkspace.
  2. The custom field must be of type Text
  3. The value of the custom field must be unique for all references within the workspace identified by rootWorkspace.

Batch Id

A Batch Id (batchId) is an optional unique identifier that can be associated with the components and references being created. The type of a Batch Id should be a string. The batch Id serves the following purposes:

  1. Allow for a component being created to be referenced within the same request.

    1. A component may use the batchId of another component in the request as the value for the parent field.
    2. A reference may use the batchId of a component in the request as the value for the source field.
    3. A reference may use the batchId of a component in the request as the value for the target field.

  2. In the response every provided batch Id will be associated with a generated OID. As the response of a batch does not guarantee any ordering, the batchId can be stored on the client side and then used to find the associated created component/reference in the response.