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:

["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.

{
  "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:

["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": "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.

We can also use an Alias href="#__codelineno-5-1">{ "components": { "create": [ { "batchId": "B", "body": { "rootWorkspace": "c253c98231776d0c8a54879e", "typeId": "p1024822409134", "name": "B", } }, { "body": { "rootWorkspace": "c253c98231776d0c8a54879e", "typeId": "p1024822409134", "name": "C", "parent": "B" } } ] } } to identify the parent component.

{
  "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

In order to delete a component you must be able to first identify it.

By Ardoq OID

If you know the Ardoq OID of the component that you wish to delete, then you can include it directly. For example, in order to delete a component with the ID "a0099b8d499b5d0001d84920" you would include the following:

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

By Alias

If you can uniquely identify the component using a combination of fields, then you can use an alias in place of an id. In this example, we know that there is exactly one component with name "A" in the workspace "c253c98231776d0c8a54879e" then we could use the following:

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

By Match

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

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 will delete ANY component with the name "A" in 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. Intuitively 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.