Warning
You are viewing documentation for a feature that is currently under incubation. This means that the feature is not yet fully supported and may change or be removed in future versions. This documentation is provided for early adopters and testers. Features under incubation should not be used in production environments.
Operations on Components
This section covers operations that can be performed on components. The following examples are intended to be illustrative and are not intended to be complete. The full schema for the Batch API can be found here.
Upsert
Warning
Upsert operations on components may not be mixed with create, update or delete operations on components in the same request.
The upsert operation uses the subset of properties listed in the uniqueBy list to match against components in Ardoq. The following rules apply:
- If NO component is matched then a new component will be created.
- If EXACTLY ONE component is matched then that component will be updated.
- If MORE THAN ONE component is matched then the request will fail.
The body of the upsert operation is the same as the create operation and (unlike update operations) must contain the rootWorkspace and typeId fields.
A batchId may be provided to identify the component being upserted. This batchId may be used as the value of the body.parent field of another component operation in the same request or as the value of the body.source or body.target fields of a reference in the same request.
By Custom Field
Custom fields are the recommended way for uniquely identifying components.
In order to identify a component by a custom field, you must provide the the following strings (in any order) in the uniqueBy list:
Where <custom_field_name> is the name of the custom field that you want to use to uniquely identify the component. We consider it a best practice to use a custom field with a meaningful name. For example - if you were modelling Jira issues in Ardoq, you might create a custom field called jira_issue_key to store the Jira issue key. You can then use this field and the id of a workspace to uniquely identify the component within a workspace.
If a component with a custom field that matches the value under body.customFields.<custom_field_name> already exists in the workspace identified by the id under body.rootWorkspace then it will be updated. If no such component exists then a new component will be created.
{
"components": {
"upsert": [
{
"batchId": "Y",
"uniqueBy": ["customFields.my_id", "rootWorkspace"],
"body": {
"rootWorkspace": "c253c98231776d0c8a54879e",
"typeId": "p1024822409134",
"name": "Component 1",
"customFields": { "my_id": "Y" }
}
}
]
}
}
By Name
In order to identify a component by name, you must provide the the following strings (in any order) in the uniqueBy list:
If a component with a name that matches the value under body.name already exists in the workspace identified by the id under body.rootWorkspace then it will be updated. If no such component exists then a new component will be created.
{
"components": {
"upsert": [
{
"batchId": "X",
"uniqueBy": ["name", "rootWorkspace"],
"body": {
"rootWorkspace": "c253c98231776d0c8a54879e",
"typeId": "p1024822409134",
"name": "X",
}
}
]
}
}
Info
While it is possible to create an Alias for a component using the componentKey field, it is not possible to use the componentKey field to identify a component in an upsert operation. This is because the value of the componentKey is generated by Ardoq when the component is created and is not known in advance.
Create
Warning
Create operations on components may not be mixed with upsert operations on components in the same request.
Create a component.
{
"components": {
"create": [
{
"body": {
"rootWorkspace": "c253c98231776d0c8a54879e",
"typeId": "p1024822409134",
"name": "A"
}
}
]
}
}
Next we create two components. In this case we set the parent of "C" to be the other component being created ("B"). We achieve this by using the value of the Batch Id.
{
"components": {
"create": [
{
"batchId": "B",
"body": {
"rootWorkspace": "c253c98231776d0c8a54879e",
"typeId": "p1024822409134",
"name": "B",
}
},
{
"body": {
"rootWorkspace": "c253c98231776d0c8a54879e",
"typeId": "p1024822409134",
"name": "C",
"parent": "B"
}
}
]
}
}
{
"aliases": {
"components": {
"C": {"name": "C", "rootWorkspace": "c253c98231776d0c8a54879e"}
}
},
"components": {
"create": [
{
"body": {
"rootWorkspace": "c253c98231776d0c8a54879e",
"typeId": "p1024822409134",
"name": "D",
"parent": "C"
}
}
]
}
}
Note
The Batch Id of a component being created or upserted may be used as the value of the body.parent of another component being created or upserted in the same request.
Update
Warning
Update operations on components may not be mixed with upsert operations on components in the same request.
In order to update a component you must be able to identify it using either its Ardoq OID or via an Alias. The body.parent field may be set to the Identifier for the parent component in the same way as in a create. This means that you can make an existing component the child of a component that is being created or upserted in the same request.
Update the component identified by an Ardoq OID
{
"components": {
"update": [
{
"id": "a0099b8d499b5d0001d84920",
"ifVersionMatch": "latest",
"body": {
"name": "Updated Component 1"
}
}
]
}
}
Update the component identified using an Alias and set the parent to a component identified using an Alias
{
"aliases": {
"components": {
"A": {"name": "A", "rootWorkspace": "c253c98231776d0c8a54879e"},
"B": {"name": "B", "rootWorkspace": "c253c98231776d0c8a54879e"}
}
},
"components": {
"update": [
{
"id": "B",
"ifVersionMatch": "latest",
"body": {
"description": "Updated Component B",
"parent": "A",
}
}
]
}
}
Delete
Warning
Delete operations on components may not be mixed with upsert operations on components in the same request.
In order to delete a component you must be able to identify it using either its Ardoq OID or via an Alias.
Delete the component identified by an Ardoq OID
Delete the component identified using an Alias.