What is nxid?
nxid is a command-line utility that you can utilize to mint ARKs from EZID, add the ARKs to Nuxeo objects, and synch the metadata from Nuxeo to EZID. If an ARK is assigned to an object in Nuxeo, the ARK will comprise part of the object's URL once published in Calisphere.
Here's an example Nuxeo object, with an ARK: https://calisphere.org/item/ark:/86086/n22b8xgh/
Here's an example Nuxeo object, without an ARK. Note that the URL reflects a Nuxeo-specific identifier: https://calisphere.org/item/40677ed1-f7c2-476f-886d-bf79c3fec8c4/
By assigning an ARK to an object, you'll thereby ensure that the object has a stable, unique identifier. Moreover, if you utilize the N2T ARK resolver service to generate permalinks for your objects, those ARK URLs can be persistently maintained -- even if the target link location of the object changes over time.
nxid is installed as part of pynux, a Python library for working with Nuxeo via its API.
To use nxid, it is helpful if you are familiar with the basic concepts of the EZID API
Getting started
First, you'll need to work with your campus library's EZID administrator, for EZID credentials. We highly recommend establishing an EZID "subaccount" for use by staff that work directly with Nuxeo -- the subaccount will allow those staff members to mint and manage ARKs that are specific to Nuxeo. We also recommend establishing a custom ARK shoulder, so it is easier to disambiguate ARKs that are specific to Nuxeo. To obtain a subaccount and custom shoulder, your administrator will need to complete and submit an EZID Shoulder Request Form.
Once the subaccount is established, your campus library EZID administrator can provide you with the username/password credentials.
Next, follow these steps to install pynux: https://github.com/ucldc/pynux . The .pynuxrc file will need to be updated, to include the username/password for your EZID subaccount.
How it works
Using nxid, you can transitively use all EZID functions (via the EZID API), to mint ARKs, bind metadata, etc.
Run nxid -h for the full set of commands and help documentation.
By default, any command inputted into nxid will initiate a "dry run" (i.e., it doesn't actually process the data), with these exceptions:
--mint: mints an ARK and also binds metadata from Nuxeo with EZID
--create: creates an ARK
--update: binds metadata from Nuxeo with EZID
Sample workflow for minting ARKs and binding Nuxeo metadata with EZID (all items in a given project folder)
nxid is highly flexible -- and depending on the state of the objects, you can selectively utilize the full range of EZID functions to manage ARKs assigned to Nuxeo. The following steps are an example workflow, for a scenario where objects are newly-built in Nuxeo -- and have no pre-existing ARKs:
Launch your python environment (with pynux installed)
Run the following command to generate an ARK status report, for items in the project folder: nxid --show-erc /asset-library/UCX/my_project_folder
The report will indicate the following options:
"Mint" = ARKs need to be minted, and the Nuxeo metadata needs to be bound with EZID (using --mint and --update)
"Update" = ARKs have already been assigned; at this point, you can re-bind the metadata with EZID (using --update) and/or update the ARK status (using --status)
It will also provide you with the current metadata for the object in EZID.
Next, run the following command to mint ARKs, bind the metadata from Nuxeo with EZID -- and also update the status of the ARKs in EZID to "unavailable" (assuming the objects are not immediately published to Calisphere):
nxid --status unavailable -mint -update /asset-library/UCX/my_project_folder
Publish the objects to Calisphere. Re-run the "--status" command again, this time bulk updating the status of the ARKs to "public":
nxid --status public --location https://calisphere.org/item/ /asset-library/UCX/my_project_folder
Sample workflow for minting ARKs and binding Nuxeo metadata with EZID (single item)
The following steps are an example workflow, for a scenario where a single object is newly-built in Nuxeo -- and has no pre-existing ARK.
Follow the same process outlined as above, but provide the specific Nuxeo path to the item when invoking the nxid command. For example:
To generate an ARK status report for the item, run: nxid "/asset-library/UCX/(remaining full path to object here)"
To mint an ARK and bind the metadata from Nuxeo with EZID, run: nxid --mint "/asset-library/UCX/(remaining full path to object here)"
Troubleshooting errors
You will encounter an error, if an object in the Nuxeo project folder has non-ARK based data inadvertently entered into the "Identifier" field.
The ARK minting and binding process will stop at that particular object. You'll want to remove the non-ARK based data from the "Identifier" field, and re-run the process -- minting and binding will resume, starting with that particular object.