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 References

Reference aliases currently allow for a limited set of fields to be used to uniquely identify a reference. Different combinations of these fields can be used to yield different search strategies. Unlike components, references are often identified by the components that they link. This means that you can use aliases for the source and target components to uniquely identify a reference.

By Custom Field

Depending on your use case it may make sense to use a custom field to uniquely identify a reference. For example, if you are integrating with a system that has first class support for references, then you might use a custom field to store the reference id of the external system.

If we assume that we have already created a reference in the workspace identified by "c253c98231776d0c8a54879e" with the custom field "link_id" set to "123", then we can create an alias for this reference.

{
  "aliases": {
    "references": {
      "link-123": {
        "rootWorkspace": "c253c98231776d0c8a54879e", 
        "customFields": {"link_id": "123"}
    }
  } 
}
The reference alias "link-123" can now be used as the identifier in either an update or delete operation.

Info

  1. You must provide the rootWorkspace that the reference 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 name of the alias may be any string that is unique within the batch request.

By Source, Target and Type

Sometimes you may expect there to exist exactly one reference of a given type between two components.

When you are working with references that are identified by the components that they link, you can use use aliases for the source and target components. For example, if you have a reference that links two components that have names that you know are unique, then you can create aliases for these components and use them in the batch request.

{"aliases": {
  "components": {
    "A": {"rootWorkspace": "c253c98231776d0c8a54879e", "name": "A"},
    "B": {"rootWorkspace": "c253c98231776d0c8a54879e", "name": "B"}
  },
  "references": {
    "A-to-B": {"source": "A", "target": "B", "type": 2}
  }
}

The reference alias "A-to-B" can now be used as the identifier in either an update or delete operation.

Info

  1. You must provide an id for the source of the reference.
  2. You must provide an id for the target of the reference.
  3. You must provide the type of the reference.
  4. No other fields may be included in the alias.
  5. The name of the alias may be any string that is unique within the batch request.