Skip to content

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.

Component aliases can be included in a batch request to uniquely identify a component. This allows you to reference existing components in the workspace without needing to know the Ardoq ID of the component. To include a component alias in a batch request, you must include the alias in the aliases.components object of the batch request.

The key of the alias object is the name of the alias that you want to use to reference the component. The value of the alias object is an object that contains the fields that you want to use to uniquely identify the component.

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 components in the workspace identified by "c253c98231776d0c8a54879e" with the custom field "jira_issue_key", then we can create an aliases for these existing components.

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

The aliases "ARD-123", "ARD-456", "ARD-789" 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 components in the workspace identified by "c253c98231776d0c8a54879e", then we can create an aliases for these existing components. 

{
  "aliases": {
    "components": {
      "id-1": {
        "rootWorkspace": "c253c98231776d0c8a54879e", 
        "name": "Component 1"
      },
      "id-2": {
        "rootWorkspace": "c253c98231776d0c8a54879e", 
        "name": "Component 2"
      },
      "id-3": {
        "rootWorkspace": "c253c98231776d0c8a54879e", 
        "name": "Component 3"
      }
    }
  }
}
The aliases "id-1","id-2","id-3" 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 components that have the Ardoq IDs "WORK-1","WORK-2","WORK-3", then we can create an aliases.

{
  "aliases": {
    "components": {
      "WORK-1": {"componentKey": "WORK-1"},
      "WORK-2": {"componentKey": "WORK-2"},
      "WORK-3": {"componentKey": "WORK-3"}            
    }
  }
}

The aliases "WORK-1","WORK-2","WORK-3" 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.