Components

Create

The Batch API enables you to create multiple components simultaneously. Simply specify the desired operations under the components.create path in the Batch payload.

Info

Using the Batch API it is possible to set a component being created as the parent of a component being created or updated in the same batch or as the source or target of a reference being created or updated in the same batch. This means that you do not need to create a component first and then use the resulting Ardoq OID in a subsequent second request.

{
  "components": {
    "create": [
      {
        "batchId": "my_batch_id",
        "body": {
          "name": "A",          
          "rootWorkspace": "c253c98231776d0c8a54879e",
          "typeId": "p1024822409134",
          "customFields": {"my_field": "X"}
        }
      },
      {        
        "body": {
          "name": "B",          
          "rootWorkspace": "c253c98231776d0c8a54879e",
          "typeId": "p1024822409134",
          "parent": "my_batch_id",
          "customFields": {"my_field": "Y"}
        }
      }      
    ]
  }
}

A create operation consists of:

• body: An object that represents the component that you are creating. It MUST include a rootWorkspace, typeId and name.
• batchId: An optional identifier provided by the user. The batchId can be referenced from other components and references in the same batch. This allows you to set a created component as the parent of another component, or as either the source or target of a reference in the same request.

The following are the most common body fields used when creating a component. The Batch API schema contains a full overview of which fields may be included.

field	Required	Description	Type
rootWorkspace	yes	The OID of the workspace that the component belongs to.	string
typeId	yes	The type identifier of the component	string
name	yes	A name for the component	string
description	no	An optional description	string
parent	no	Parent identifier. May be an OID or a Batch Id	string
customFields	no	Custom fields and values for the component.	object

Update

The Batch API enables you to modify multiple components simultaneously. Simply specify the desired operations under the components.update path in the Batch payload.

{
  "components": {
    "update": [
      {
        "id": "65970becbc241d0001ccdd43",
        "ifVersionMatch": "latest",
        "body": {
          "customFields": {"my_other_field": 100}
        }
      },
      {
        "id": "c253c98231776d0c8a54879e",
        "ifVersionMatch": 16,       
        "body": {
          "parent": null,
          "customFields": {"my_other_field": 42}
        }
      }
    ]
  }
}

An update operation consists of the following:

• id: The Ardoq OID of the component that you are updating.
• ifVersionMatch: Either the current version (integer) of the component that you are updating or the string "latest" that will implicitly use the latest version. For more information we have a section that covers versioning. For most use cases simply using "latest" is fine.
• body: An object that represents the changes that you wish to make.

When updating a component only the fields included in the body will be updated. The Batch API schema contains a full overview of which fields may be included. The most important are:

field	Required	Description	Type
name	no	A name for the component	string
description	no	An optional description	string
parent	no	Parent identifier	string or null if you wish to 'unset' the parent.
customFields	no	Custom fields and values for the component.	object

Delete

The Batch API enables you to delete multiple components simultaneously. Simply specify the desired operations under the components.delete path in the Batch payload.

{
  "components": {
    "delete": [
      {"id": "65970becbc241d0001ccdd43"},
      {"id": "c253c98231776d0c8a54879e"},
      {"id": "4b131856bb51f7fa1aace0db"}      
    ]
  }
}

A delete operation consists of the following:

• id: The Ardoq OID of the component that you are deleting.