Skip to content

About

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.

View the full schema here.

The Batch API lets you combine create, update, upsert (update an existing entity or create a new one) and delete operations on both components and references into a single request. All operations are executed within a transaction. If any of the operations fail then the whole request will fail leaving the state of Ardoq unmodified. The Batch API aims to be:

  • Efficient - By combining multiple operations into a single request, the number of HTTP requests that need to be made to the API is reduced. The Batch API also supports Unique By identifiers that allow you to identify components and references without needing to know their Ardoq OIDs. This means that you can create, update and delete components and references without needing to first fetch data from Ardoq.
  • Flexible - You can use a combination of Batch Ids and Unique By identifiers to create and modify components and references without needing to know their Ardoq OIDs. This makes it possible to create and modify complex structures in Ardoq with a single request without needing to pre-fetch the Ardoq OID of each entity.
  • Safe - All operations are executed within a transaction. If any of the operations fail then the whole request will fail leaving the state of Ardoq unmodified.

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.

Create

Create a component and provide the Ardoq OID of the parent component. If your component does not have a parent then the field may be omitted.

{
  "components": {
    "create": [
      {
        "body": {
          "rootWorkspace": "c253c98231776d0c8a54879e",
          "typeId": "p1024822409134",
          "name": "Component 1",
          "parent": "6509b612499b5d0001d84921"
        }
      }
    ]
  }
}

Next we create two components. In this case we set the parent of "Component 3" to be the other component being created. We achieve this by using the value of the Batch Id.

{
  "components": {
    "create": [
      {
        "batchId": "Batch-Id-1",
        "body": {
          "rootWorkspace": "c253c98231776d0c8a54879e",
          "typeId": "p1024822409134",
          "name": "Component 2",
        }
      },
      {
        "body": {
          "rootWorkspace": "c253c98231776d0c8a54879e",
          "typeId": "p1024822409134",
          "name": "Component 3",
          "parent": "Batch-Id-1"
        }
      }
    ]
  }
}
We can also use a Unique By identifier to identify the parent component.

{
  "components": {
    "create": [
      {
        "body": {
          "rootWorkspace": "c253c98231776d0c8a54879e",
          "typeId": "p1024822409134",
          "name": "Component 4",
          "parent": {"customField": "my_id","value": "1","rootWorkspace":"c253c98231776d0c8a54879e"}
        }
      }
    ]
  }
}

Note

A "Unique By" identifier may also be used to reference a component that is being upserted in the same request.

Upsert

The upsert operation will update a component if it already exists or create the component if it does not exist. This means that the body data must contain all of the fields required for a create operation. In order to upsert a component you must be able to identify it using a Unique By identifier. 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. You must ensure that the custom field and value used to identify the component are included in the body of the component being upserted.

Upsert a single component

{
  "components": {
    "upsert": [
      {
        "id": {"customField": "my_id","value": "1","rootWorkspace":"c253c98231776d0c8a54879e"},
        "body": {
          "rootWorkspace": "c253c98231776d0c8a54879e",
          "typeId": "p1024822409134",
          "name": "Component 1",
          "customFields": { "my_id": "1" }
        }
      }
    ]
  }
}

In the following example we upsert two components and set the parent of "Component 2" to be "Component 1". A Unique By identifier is used to identify the parent component as it is also being upserted.

{
  "components": {
    "upsert": [
      {
        "id": {"customField": "my_id","value": "1","rootWorkspace":"c253c98231776d0c8a54879e"},
        "body": {
          "rootWorkspace": "c253c98231776d0c8a54879e",
          "typeId": "p1024822409134",
          "name": "Component 1",
          "customFields": { "my_id": "1" }
        }
      },
      {
        "id": {"customField": "my_id","value": "2","rootWorkspace":"c253c98231776d0c8a54879e"},
        "body": {
          "rootWorkspace": "c253c98231776d0c8a54879e",
          "typeId": "p1024822409134",
          "name": "Component 2",
          "customFields": {"my_id": "2"},
          "parent": {"customField": "my_id","value": "1","rootWorkspace":"c253c98231776d0c8a54879e"},
        }
      }
    ]
  }
}

Update

In order to update a component you must be able to identify it using either its Ardoq OID or a Unique By identifier. 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 a Unique By and set the parent to a component identified using a Unique By

{
  "components": {
    "update": [
      {
        "id": {"customField":"my_id", "value":"2", "rootWorkspace":"c253c98231776d0c8a54879e"},
        "ifVersionMatch": "latest",
        "body": {
          "name": "Updated Component 2",
          "parent": {"customField":"my_id","value":"1","rootWorkspace":"c253c98231776d0c8a54879e"},
        }
      }
    ]
  }
}

Delete

In order to delete a component you must be able to identify it using either its Ardoq OID or a Unique By identifier.

Delete the component identified by an Ardoq OID

{
  "components": {
    "delete": [
      {"id": "a0099b8d499b5d0001d84920"}
    ]
  }
}

Delete the component identified using a Unique By.

{
  "components": {
    "delete": [
      {"id": {"customField": "my_id", "value": "2", "rootWorkspace": "c253c98231776d0c8a54879e"}}
    ]
  }
}

References

Create

{
  "references": {
    "create": [
      {
        "body": {
          "source": "6509b612499b5d0001d84921",
          "target": "4b131856bb51f7fa1aace0db",
          "type": 2
        }
      }
    ]
  }
}

In the same way that a component may have its body.parent field set to an Identifier, a reference may have its body.source and body.target set - both of which are components. In this example we use a Batch Id to identify the source and a Unique By to identify the target.

{
  "references": {
    "create": [
      {
        "body": {
          "source": "Batch-Id-1",
          "target": {"customField": "my_id","value": "1","rootWorkspace":"c253c98231776d0c8a54879e"},
          "type": 2
        }
      }
    ]
  },
  "components": {
    "create": [
      {
        "batchId": "Batch-Id-1",
        "body": {
          "rootWorkspace": "c253c98231776d0c8a54879e",
          "typeId": "p1024822409134",
          "name": "Component 2",
        }
      }
    ]
  }
}

Upsert

The upsert operation will update a reference if it already exists or create the reference if it does not exist. This means that the body data must contain all of the fields required for a create operation. In order to upsert a reference you must be able to identify it using a Unique By identifier. The body.source and body.target fields may be set to an Identifier for the desired components in the same way as in a create. You must ensure that the custom field and value used to identify the reference are included in the body of the reference being upserted.

Upsert a single reference

{
  "references": {
    "upsert": [
      {
        "id": {"customField":"ref_id","value": "XYZ","rootWorkspace":"c253c98231776d0c8a54879e"},
        "body": {
          "source": "6509b612499b5d0001d84921",
          "target": "4b131856bb51f7fa1aace0db",
          "type": 2,
          "customFields": {"ref_id": "XYZ"}
        }
      }
    ]
  }
}
Upsert a reference and set the source and target to components that are being upserted in the same request. Note that the ref_id value is based on the my_id values of the components being upserted and the type of the reference. This is to ensure that there can only exist one reference of this type between these two components.

{
  "references": {
    "upsert": [
      {
        "id": {"customField": "ref_id","value": "a-2-b","rootWorkspace":"c253c98231776d0c8a54879e"},        
        "body": {
          "source": {"customField": "my_id","value": "a","rootWorkspace":"c253c98231776d0c8a54879e"},
          "target": {"customField": "my_id","value": "b","rootWorkspace":"c253c98231776d0c8a54879e"},
          "type": 2,
          "customFields": {"ref_id": "a-2-b"}
        }
      }      
    ]
  },
  "components": {
    "upsert": [
      {
        "id": {"customField": "my_id","value": "a","rootWorkspace":"c253c98231776d0c8a54879e"},
        "body": {
          "rootWorkspace": "c253c98231776d0c8a54879e",
          "typeId": "p1024822409134",
          "name": "Component 1",
          "customFields": {"my_id": "a"}
        }
      },
      {
        "id": {"customField": "my_id","value": "b","rootWorkspace":"c253c98231776d0c8a54879e"},
        "body": {
          "rootWorkspace": "c253c98231776d0c8a54879e",
          "typeId": "p1024822409134",
          "name": "Component 2",
          "customFields": {"my_id": "b"}
        }
      }
    ]
  }
}

Update

In order to update a reference you must be able to identify it using either its Ardoq OID or a Unique By identifier. The body.source and body.target fields may be set to the Identifier of a component in the same way as when creating.

Update the reference identified by an Ardoq OID

{
  "components": {
    "update": [
      {
        "id": "a0099b8d499b5d0001d84920",
        "ifVersionMatch": "latest",
        "body": {
          "displayText": "Updated Reference"
        }
      }
    ]
  }
}

Update the reference identified using a Unique By and set the source to a component identified using a Unique By

{
  "references": {
    "update": [
      {
        "id": {"customField": "ref_id", "value": "XYZ", "rootWorkspace": "c253c98231776d0c8a54879e"},
        "ifVersionMatch": "latest",
        "body": {
          "source": {"customField": "my_id", "value": "1", "rootWorkspace": "c253c98231776d0c8a54879e"}
        }
      }
    ]
  }
}

Delete

In order to delete a reference you must be able to identify it using either its Ardoq OID or a Unique By identifier.

Delete the reference identified by an Ardoq OID

{
  "references": {
    "delete": [
      {"id": "a0099b8d499b5d0001d84920"}
    ]
  }
}

Delete the reference identified using a Unique By.

{
  "references": {
    "delete": [
      {"id": {"customField": "my_id", "value": "2", "rootWorkspace": "c253c98231776d0c8a54879e"}}
    ]
  }
}