Skip to content

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 references in the workspace identified by "c253c98231776d0c8a54879e" with the custom field "link_id", then we can create aliases.

{
  "aliases": {
    "references": {
      "link-123": {
        "rootWorkspace": "c253c98231776d0c8a54879e", 
        "customFields": {"link_id": "123"}
      },
      "link-456": {
        "rootWorkspace": "c253c98231776d0c8a54879e", 
        "customFields": {"link_id": "456"}
      },
      "link-789": {
        "rootWorkspace": "c253c98231776d0c8a54879e", 
        "customFields": {"link_id": "789"}
      }

    }
  }
}
The reference aliases "link-123","link-456","link-789" can now be used as identifiers 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 and Type

Help

You can read more about uniquely identifying references by source and type in the Upsert operation section of references.

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

The reference alias "A-to-something" 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 the type of the reference.
  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 Target and Type

Help

You can read more about uniquely identifying references by target and type in the Upsert operation section of references.

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

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

Info

  1. You must provide an id for the target of the reference.
  2. You must provide the type of the reference.
  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

Help

You can read more about uniquely identifying references by source, target and type in the Upsert operation section of references.

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