Operations on Components

This section covers operations that can be performed on components. The following examples are intended to be illustrative and are not complete. The full schema for the Batch API can be found here.

Create

Info

If your components are uniquely identifiable within a workspace we recommend that you use the new upsert operation.

• You can create multiple components by including them in the create list.

• A component may have an optional batchId field that can be used to reference the component in the same request. The value of the batchId field is a user-defined string that can be used to identify the component in the same request.

• A component may have an optional parent field that can be used to identify the parent of the component being created. The value of the parent field is the Identifier of the parent component.

As an example, the following request will create two components in the same workspace. The first component will be the parent of the second component. We use the batchId value to reference the components in the same request.

{
  "components": {
    "create": [
      {
        "batchId": "A",        
        "body": {
          "rootWorkspace": "c253c98231776d0c8a54879e",
          "typeId": "p1024822409134",
          "name": "Component A"
        }
      },
      {
        "batchId": "B",        
        "body": {
          "rootWorkspace": "c253c98231776d0c8a54879e",          
          "typeId": "p2874929873892",
          "name": "Component B",
          "parent": "A"
        }
      }
    ]
  }
}

If your parent component already exists in Ardoq then you can either use the Ardoq OID of the parent component as the value of the body.parent field or use an Alias to identify the parent component.

In the following example, the parent component with batchId "D" is identified using an Alias and the parent component with batchId "E" is identified using the Ardoq OID.

{
  "aliases": {
    "components": {      
      "B": {"name": "Component B", "rootWorkspace": "c253c98231776d0c8a54879e"}      
    }
  },  
  "components": {
    "create": [
      {
        "batchId": "D",        
        "body": {
          "rootWorkspace": "c253c98231776d0c8a54879e",          
          "typeId": "p2874929873892",
          "name": "Component D",
          "parent": "B"
        }
      },
      {
        "batchId": "E",        
        "body": {
          "rootWorkspace": "c253c98231776d0c8a54879e",          
          "typeId": "p2874929873892",
          "name": "Component E",
          "parent": "91ab09087115f76e365134c5"
        }
      },
    ]
  }
}

Update

Info

If your components are uniquely identifiable within a workspace we recommend that you use the new upsert operation.

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.

• You can update multiple components by including them in the update list.

• When updating a component you must provide the id field. This field is the Identifier of the component that you want to update. It may either be an Ardoq OID of the component or an Alias that uniquely identifies the component.

• When updating a component you must provide the ifVersionMatch field. This field can be set to either "latest" or a specific version number. If the value of the ifVersionMatch field is "latest" then the latest version of the component will be updated. If the value of the ifVersionMatch field is a specific version number then the component will only be updated if the version number of the component matches the value of the ifVersionMatch field. If the version number of the component does not match the value of the ifVersionMatch field then the update operation will fail.

• The body of the update operation only needs to contain the fields that you want to update. You do not need to provide all of the fields of the component.

In the following example we update a component identified by an alias and set the parent of the component to another component identified by 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",
        }
      }
    ]
  }
}

Upsert

Info

If your components are uniquely identifiable within a workspace we recommend that you use this new upsert operation.

Upserting is the process of creating a new component if it does not already exist or updating an existing component if it does. This is particularly useful when writing a custom integration as you can ensure that a component is created or updated in Ardoq without needing to check if it already exists.

An upsert operation is identical to a create operation with the addition of a uniqueBy list. This list is used to uniquely identify the component that is being upserted.

The following rules apply:

1. If NO component is matched then a new component will be created.
2. If EXACTLY ONE component is matched then that component will be updated.
3. If MORE THAN ONE component is matched then the request will fail.

Warning

To avoid ambiguity, you may NOT include create or update operations on components when upserting components.

The uniqueBy list is a list of strings that correspond to the fields that are used to uniquely identify the component. The order of the strings in the uniqueBy list is not important.

Currently there a two ways to uniquely identify a component:

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:

["customFields.<custom_field_name>", "rootWorkspace"]

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.

In the following example we upsert two components. The first component has a custom field my_id with the value "AAA" and the second component has a custom field my_id with the value "BBB". The first component is the parent of the second component. Note that in this example it does not matter if either of the components already exist in the workspace.

{
  "components": {
    "upsert": [
      {
        "batchId": "A",
        "uniqueBy": ["customFields.my_id", "rootWorkspace"],
        "body": {
          "rootWorkspace": "c253c98231776d0c8a54879e",
          "typeId": "p1024822409134",
          "name": "Component A",
          "customFields": { "my_id": "AAA" }
        }
      },
      {
        "batchId": "B",
        "uniqueBy": ["customFields.some_other_id", "rootWorkspace"],        
        "body": {
          "rootWorkspace": "c253c98231776d0c8a54879e",
          "typeId": "p2874929873892",
          "name": "Component B",
          "parent": "A",
          "customFields": { "my_id": "BBB" }
        }
      }
    ]
  }
}

By Name

Upserting by name is the simplest way to upsert a component, however it is also the least flexible. If you use an id as the name of a component then it becomes harder to intuitively understand what the component represents.

In order to identify a component by name, you must provide the the following strings (in any order) in the uniqueBy list:

["name", "rootWorkspace"]

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": "A",
        "uniqueBy": ["name", "rootWorkspace"],
        "body": {
          "rootWorkspace": "c253c98231776d0c8a54879e",
          "typeId": "p1024822409134",
          "name": "Some Org"
        }
      },
      {
        "batchId": "B",
        "uniqueBy": ["name", "rootWorkspace"],
        "body": {
          "rootWorkspace": "c253c98231776d0c8a54879e",
          "typeId": "p2874929873892",
          "name": "Some Department",
          "parent": "A"          
        }
      }
    ]
  }
}

Delete

There are three ways to delete components from Ardoq:

By Ardoq OID

If you know the Ardoq OID of the component that you wish to delete, then you can include it directly:

{
  "components": {
    "delete": [
      {"id": "a0099b8d499b5d0001d84920"},
      {"id": "65970082bc241d0001ccdd4b"}
      {"id": "63ea1a02bbed2e0001a19a9c"}
    ]
  }
}

By Alias

If you can uniquely identify the component using a combination of fields, then you can use an alias in place of an Ardoq ID:

{
  "aliases": {
    "components": {
      "A": {"name": "A", "rootWorkspace": "c253c98231776d0c8a54879e"},
      "B": {"name": "B", "rootWorkspace": "c253c98231776d0c8a54879e"}, 
      "C": {"name": "C", "rootWorkspace": "c253c98231776d0c8a54879e"}      
    }
  },
  "components": {
    "delete": [
      {"id": "A"},
      {"id": "B"},
      {"id": "C"} 
    ]
  }
}

By Match (Smart Delete)

Deleting by match is the most powerful way of deleting components from Ardoq.

It can be combined with upsert operations to ensure that components are deleted if they are no longer needed.

A match is an object with a single key "match" whose value is identical to that of an alias. However, unlike aliases and the uniqueBy of an upsert a match object is expected to correspond to zero or more components. Thus, in the following example ANY component with the name "A" will be deleted from the workspace "c253c98231776d0c8a54879e"; be that zero, one or more.

{
  "components": {
    "delete": [      
      {"match": {"name": "A", "rootWorkspace": "c253c98231776d0c8a54879e"}}
    ]
  }
}

This differs from aliases that must match exactly one entity.

The following table covers the combinations of fields that can be used to identify a component in a match object.

rootWorkspace	typeId	name	componentKey	customFields.<X>
✅
			✅
✅	✅
✅		✅
✅				✅

Dependencies

One important aspect of deleting by match is that components that are dependencies of a Batch request WILL NOT be deleted. This means that you can not delete components that are "required" by components and references that you are creating/updating at the same time.

• Every created component is a dependency.
• Every updated component is a dependency.
• Every upserted component is a dependency.
• Every component that is the parent of a component dependency after performing the create,update and upsert operations is a dependency. In other words, the full parent hierarchy is preserved for all created, updated and upserted components.
• Every component that is the source or target of a reference dependency is a dependency. This ensures that you can not delete the source or target of a reference that you are creating, updating and upserting.