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.

Aliasing Components

Component aliases currently allow for a limited set of fields to be used to uniquely identify a component. Different combinations of these fields can be used to yield different search strategies.

By Custom Field

Custom fields are the recommended way for uniquely identifying components. 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 we assume that we have already created a component in the workspace identified by "c253c98231776d0c8a54879e" with the custom field "jira_issue_key" set to "ARD-123", then we can create an alias for this component.

{
  "aliases": {
    "components": {
      "ARD-123": {
        "rootWorkspace": "c253c98231776d0c8a54879e", 
        "customFields": {"jira_issue_key": "ARD-123"}}
    }
  } 
}

The alias "ARD-123" can now be used anywhere in the batch request that requires a component identifier, either as a source or target of a reference, as a parent of a component or as the identifier of a component to be updated or deleted.

Info

  1. You must provide the rootWorkspace that the component belongs to.
  2. You may only specify a single custom field. In other words, the customFields object may only contain a single key-value pair.
  3. No other fields may be included in the alias.
  4. The provided name of the alias identifier may be any string that is unique within the batch request.

By Name

While we recommend using a custom field to uniquely identify a component, it is possible to use the name of a component to uniquely identify it within a workspace. Using a name simplifies the need to manage custom fields, however you loose the meaning of the identifier.

If we assume that we have already created a component in the workspace identified by "c253c98231776d0c8a54879e" with the "name" set to "Component 1", then we can create an alias for this component. 

{
  "aliases": {
    "components": {
      "id-1": {
        "rootWorkspace": "c253c98231776d0c8a54879e", 
        "name": "Component 1"
    }
  } 
}
The alias "id-1" can now be used anywhere in the batch request that requires a component identifier, either as a source or target of a reference, as a parent of a component or as the identifier of a component to be updated or deleted.

Info

  1. You must provide the rootWorkspace that the component belongs to.
  2. You must provide the name of the component.
  3. No other fields may be included in the alias.
  4. The provided name of the alias identifier may be any string that is unique within the batch request.

By Ardoq ID

A component key is a unique human readable ID of a component. It is referred to as the "Ardoq ID" in the App. The component key is generated by Ardoq and is unique across all workspaces.

If we assume that we have already created a component that has the Ardoq ID "WORK-1", then we can create an alias for this component.

{
  "aliases": {
    "components": {
      "WORK-1": {"componentKey": "WORK-1"}
    }
  }
}

The alias "WORK-1" can now be used anywhere in the batch request that requires a component identifier, either as a source or target of a reference, as a parent of a component or as the identifier of a component to be updated or deleted.

Info

  1. You must provide the componentKey value.
  2. No other fields may be included in the alias.
  3. The provided name of the alias identifier may be any string that is unique within the batch request.