Handles Implementation
Handles are a kind of persistent identifier, similar to DOIs or ARKs. They used for citations, online stability for digital objects, and linkages between like collections objects.
Handles consist of two parts: a prefix and a suffix. Prefixes are minted through CNRI and are specific to each entity that requests one. Currently, we maintain one prefix for the DAMS/Collections Portal: 20.500.14725 This means that all assets in the DAMS/Collections Portal that have a Handle will use 20.500.14725 as its prefix. Suffixes are usually an unique, randomly assigned value. These are located after the prefix and are unique to that asset or object being assigned the Handle. See example Handle below:
Handles are managed locally in a self-hosted server, as well as being stored in the global Handle server. All Handles, whether active or non-resolvable, are recorded in the Handle server.
UTL Handles follow PID best practices. Handles are unique and non-semantic (i.e. they do not have phrases or IDs that have conceptual meaning) and they are not case-sensitive.
Site Implementation:
DAMS
Used at the asset level only.
Utilizes an opaque, non-semantic prefix.
Utilizes DAMS node id for the suffix.
Only applies to published assets.
Created upon publishing. If an asset is unpublished, the Handle remains with the asset unchanged. If the asset is deleted, the Handle is deleted, but a record remains in the local Handle server. See flow diagram below:
Are displayed in the Identifier field.
Are in a separate Identifier field from other items (not concatenated), and should have their own identifier type, “Handle,” to differentiate from other PIDs.
Some assets will have multiple Handles from other sites/repositories (ex. GeoData Portal assets having their own Handles and other Handles that resolve to the same item in the Collections Portal.)
Separate prefixes from other sites/repositories in the DAMS. For example, the GeoData Portal has a different prefix from the Collections Portal.
Appear in the IIIF manifest alongside other metadata fields.
Do not replace an asset’s url, but simply resolve to it.
ArchivesSpace
Used at the asset level only, specifically digital object records.
Only applies to published assets.
Will be displayed in the File URI field.
Handles will not be minted in ArchivesSpace, but instead be retrieved from the DAMS.
Texas ScholarWorks
Uses Handles and DOIs at both collection and asset level.
Are displayed in the dc.identifier.uri field.
Created upon publishing.
Are managed using a separate database.
Handle Requests
Request | Action |
|---|---|
POST | create a Handle; this action fails if a Handle already exists |
POST | update a Handle’s url; this action fails if the Handle is missing or deleted |
DELETE | delete a Handle; this action fails if the Handle is missing or deleted |
GET | checks on the status of a Handle request |
GET | resolve a Handle to its url |
GET | list current local Handles (from our PostgresSQL database) |
GET | list/retrieve remote Handles (from the BerkeleyDB) |
Handle Metadata Structure
Handles contain basic metadata that is available once a request is made.
These fields are outlined below:
Request Body Fields:
handle: the unique suffix. ex. Handle123
url: any url that one would like to enter. ex. a url used in the Collections Portal
Response Body Fields:
id: id for the request, can use this to check on status of request.
op: what request one is running. etc. “create”
full_handle: the standard prefix. ex. 20.500.14725 (current DAMS prefix.)
url: the url that was entered in the Request Body url field.
attempts: how many times an action has been attempted on a Handle.
status: queued, running, success, and error as expected values.
javastdout: what the Handle server is returning, usually a message about if the Handle was created, updated, or deleted.
java_stderr: if there is an error, will get error code here.
error: if there is an error, will get error code here.