Skip to content

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 References

Upsert

Warning

Upsert operations on references may not be mixed with create, update or delete operations on references in the same request.

The upsert operation uses the subset of properties listed in the uniqueBy list to match against references in Ardoq. The following rules apply:

  1. If NO reference is matched then a new reference will be created.
  2. If EXACTLY ONE reference is matched then that reference will be updated.
  3. If MORE THAN ONE reference 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 source, target and type fields. Note that the source and target fields may any of the Identifier types.

A batchId may be provided to identify the reference being upserted.

By Custom Field

Gotcha

The string "source.rootWorkspace" must be included in the uniqueBy list when identifying references by custom field, not "rootWorkspace". This is because the rootWorkspace is not included in the body of the reference and is derived from the source field.

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

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

Where <custom_field_name> is the name of the custom field that you want to use to uniquely identify the reference.

If a reference with a custom field that matches the value under body.customFields.<custom_field_name> already exists in the workspace that the body.source component belongs to then it will be updated. If no such reference exists then a new reference will be created.

{
  "references": {
    "upsert": [
      {
        "batchId": "Y",
        "uniqueBy": ["customFields.ref_id", "source.rootWorkspace"],
        "body": {
          "source": "6509b612499b5d0001d84921",
          "target": "4b131856bb51f7fa1aace0db",
          "type": 2,
          "customFields": {"ref_id": "XYZ"}
        }
      }
    ]
  }
}

By Source, Target and Type

In order to identify a reference by source, target and type, you must provide the the following strings (in any order) in the uniqueBy list:

["source", "target", "type"]

If a reference with a source that matches the value under body.source a target that matches the value under body.target and a type that matches the value under body.type already exists then it will be updated. If no such reference exists then a new reference will be created.

In other words, this lets you ensure that there is only one reference of a certain type between two components which can be useful in many cases.

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

Create

Warning

Create operations on references may not be mixed with upsert operations on references in the same request.

{
  "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 (both of which are components) set. In this example we use an Alias to identify the source and a Batch Id to identify the target.

{
  "aliases": {
    "components": {
      "A": {"name": "A", "rootWorkspace": "c253c98231776d0c8a54879e"},      
    }
  },  
  "components": {
    "create": [
      {
        "batchId": "B",
        "body": {
          "rootWorkspace": "c253c98231776d0c8a54879e",
          "typeId": "p1024822409134",
          "name": "B",
        }
      },
    ]
  },
  "references": {
    "create": [
      {
        "body": {
          "source": "A",
          "target": "B",
          "type": 2
        }
      }
    ]
  }
}

Update

Warning

Update operations on references may not be mixed with upsert operations on references in the same request.

In order to update a reference you must be able to identify it using either its Ardoq OID or an Alias. The body.source and body.target fields may be set to the Identifier of a component.

Update the reference identified by an Ardoq OID

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

Update the reference identified using an Alias and set the target to a component identified using an Alias

{
  "aliases": {
    "components": {
      "A": {"name": "A", "rootWorkspace": "c253c98231776d0c8a54879e"},
      "B": {"name": "B", "rootWorkspace": "c253c98231776d0c8a54879e"}, 
      "C": {"name": "C", "rootWorkspace": "c253c98231776d0c8a54879e"},             
    },
    "references": {
      "A-2-B": {"source": "A", "target": "B", "type": 2}
    }
  },
  "references": {
    "update": [
      {
        "id": "A-2-B",
        "ifVersionMatch": "latest",
        "body": {
          "target": "C"
        }
      }
    ]
  }
}

Delete

Warning

Delete operations on references may not be mixed with upsert operations on references in the same request.

In order to delete a reference you must be able to identify it using either its Ardoq OID or an Alias.

Delete the reference identified by an Ardoq OID

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

Delete the reference identified using an Alias.

{
  "aliases": {
    "components": {
      "A": {"name": "A", "rootWorkspace": "c253c98231776d0c8a54879e"},
      "B": {"name": "B", "rootWorkspace": "c253c98231776d0c8a54879e"}      
    },
    "references": {
      "A-2-B": {"source": "A", "target": "B", "type": 2}
    }
  },
  "references": {
    "delete": [
      {"id": "A-2-B"}
    ]
  }
}