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:
- 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 fieldmy_id
, then the custom fieldmy_id
must be defined for either all component types in the workspace identified byrootWorkspace
or explicitly theServer
type defined in the workspace identified byrootWorkspace
. - The custom field must be of type Text
- 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:
- 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 fieldmy_id
, then the custom fieldmy_id
must be defined for either all reference types in the workspace identified byrootWorkspace
or explicitly theBelongs To
type defined in the workspace identified byrootWorkspace
. - The custom field must be of type Text
- 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:
-
Allow for a component being created to be referenced within the same request.
- A component may use the
batchId
of another component in the request as the value for theparent
field. - A reference may use the
batchId
of a component in the request as the value for thesource
field. - A reference may use the
batchId
of a component in the request as the value for thetarget
field.
- A component may use the
-
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.