External identifiers [VC 21.3 GEN]

External ids can be set on entities to provide an alternate way of accessing them. For example, instead of using the id VX-100 to access a particular storage, a custom external id such as example_storage can be used.

An external id is defined as the triple (entity type, namespace, value) and must be unique among the same entity type. The namespace is defined as the tuple (name, regular expression), where the regular expression is used to determine which namespace a given external id belongs to. It is therefore preferred that the set of possible values of a regular expression for a namespace is disjoint from the set of values for another namespace. Further note that set of values must also be disjoint from any ids generated by the system.

Managed namespaces using the namespace resource.

Priority

If the sets of possible values for all namespaces are disjoint, then no conflict exists. However, if they do have values in common there is an ambiguity regarding which namespace a particular value belongs to. This ambiguity is solved by that all namespaces have a priority value. Upon retrieving the namespaces they will be sorted in ascending ordering according to the priority value (thus making a namespace with a smaller value more important than a namespace with a larger value).

Example

Given two namespaces, N1, matching alphanumeric strings, and N2, matching all strings, with N1 being more important than N2, then N1 will always match alphanumeric strings and N2 will match all other strings.

Namespace	Pattern	Priority
N1	`[a-zA-Z0-9]+`	5
N2	`.+`	10

If the priority values were reversed so that N2 had the smaller priority value, it would match all strings and N1 would match no strings.

Example: The UUID namespace

In this example we will create a namespace for UUIDs and assign a UUID as an external identifier for an item.

First we create the namespace and simply name it “uuid”.

NONE

PUT /external-id/uuid
Content-Type: application/xml

<ExternalIdentifierNamespaceDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    <pattern>[A-Fa-f0-9]{8}\-[A-Fa-f0-9]{4}\-[A-Fa-f0-9]{4}\-[A-Fa-f0-9]{4}\-[A-Fa-f0-9]{12}</pattern>
    <priority>10</priority>
</ExternalIdentifierNamespaceDocument>

Then we assign a UUID to the item VX-11.

NONE

PUT /item/VX-11/external-id/69e436fe-eaed-4061-a66b-7d7c4bf80b20

Retrieving the definition:

NONE

GET /item/69e436fe-eaed-4061-a66b-7d7c4bf80b20/external-id

HTML/XML

<ExternalIdentifierListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <id>
    <entityId>VX-11</entityId>
    <entityType>Item</entityType>
    <namespace>uuid</namespace>
    <externalId>69e436fe-eaed-4061-a66b-7d7c4bf80b20</externalId>
  </id>
</ExternalIdentifierListDocument>