.. _UC38:

Use Case 38 - Reserve an Identifier
-----------------------------------

.. index:: Use Case 38, UC38, reserve identifier

Revisions
  View document revision history_.

Goal
  Reserve an identifier to ensure it is available at some reasonable time in
  the future.

Summary
  As new content is added to the DataONE system, it is desirable to reserve an
  identifier in advance of creating the content as it is necessary for the
  client to generate relationships between content that may not exist in the
  DataONE system (e.g. a new data set with associated science metadata).

Actors
  ITK, Coordinating Node

Preconditions
  - CN and MN operational

Triggers
  - A client needs to reserve an identifier so that associations can be
    created in the system metadata

Post Conditions
  - An identifier is reserved and guaranteed to be unique for some finite
    period of time.

.. uml::

   usecase "12. Authentication" as authen
   package "DataONE"
     actor "Coordinating Node" as CN
     actor "Client" as ITK
     usecase "13. Authorization" as author
     usecase "38. Reserve Identifier" as RES
     CN -- RES
     ITK -- RES
     RES ..> author: <<includes>>
     RES ..> authen: <<includes>>

*Figure 1.* Use case 38. Note that id a Member Node needs to reserve an
identifier then it would use the functioanlity of the Investigator Toolkit
Library - that is, the reserveIdentifier operation is not required for Member
Node functionality.

.. uml::

   participant "Client" as itk <<Investigator Toolkit>>
   participant "CRUD API" as c_crud << Coordinating Node >>
   itk -> c_crud: reserveIdentifier(token, pid, scope, format)
   c_crud -> c_crud: createDummyEntry
   note right
     A dummy entry is created in the object store as a place holder.
     This entry should not be retrievable through search or other
     discovery mechanisms.
   end note
   alt Not Authorized
     c_crud -> itk: NotAuthorized
   else Identifier Exists
     c_crud -> itk: NotUnique
   else ok
     c_crud -> itk: identifier
   end

*Figure 2.* Sequence diagram for use case 38. The Coordinating Node needs to
keep track of identifiers that have been reserved, and this information needs
to be replicated between Coordinating Nodes. The reserved identifier should
not be discoverable and should not be involved with any Member Node
synchronization or Member Node replication.

.. _history: https://redmine.dataone.org/projects/d1/repository/changes/documents/Projects/cicore/architecture/api-documentation/source/design/UseCases/38_uc.txt