.. _UC37:

Use Case 37 - Get System Metadata for Object
--------------------------------------------

.. index:: Use Case 37, UC37, getSystemMetadata, system metadata

Revisions
  View document revision history_.

Goal
  Retrieve the :term:`system metadata` for an object identified by some :term:`identifier`.

Summary 
  A client has an identifier for some object within the DataONE system and is
  attempting to retrieve system metadata describing the object. If the object
  exists on the node and the user has READ permission on the object, then the
  bytes of the system metadata object are returned, otherwise an error
  condition occurs.

  Note that Member Nodes do not store authoritative copies of system metadata,
  but they still need to implement this operation.

Actors
  - Client requesting object
  - Coordinating Node
  - Member Node

Preconditions 
  - Client has authenticated to the desired level (e.g. client may not have
    authenticated, so access might be anonymous).

Triggers
  - System metadata is requested from the DataONE system.

Post Conditions
  - The client has a copy of the system metadata document (or an error message
    in the case of failure)


.. 
   @startuml images/36_uc.png
   actor "User" as client
   usecase "12. Authentication" as authen
   note top of authen
   Authentication may be provided 
   by an external service
   end note

   package "DataONE"
     actor "Coordinating Node" as CN
     actor "Member Node" as MN
     usecase "13. Authorization" as author
     usecase "01. Get System Metadata" as GET
     client -- GET
     CN -- GET
     MN -- GET
     GET ..> author: <<includes>>
     GET ..> authen: <<includes>>
   @enduml

.. image::  images/36_uc.png

*Figure 1.* Use case 37 diagram showing actors and components involved in this action.


.. 
   @startuml images/36_seq.png
   participant "Client" as app_client << Application >>
   participant "CRUD API" as n_crud << Node >>
   participant "Authorization API" as n_authorize <<  Node >>
   participant "Object Store" as n_ostore << Node >>
   app_client -> n_crud: getSystemMetadata(token, PID)
   activate app_client
   activate n_crud
   n_crud -> n_authorize: isAuthorized(token, PID, READ)
   n_crud <- n_authorize: True, False, Err.NotFound
   alt NotFound
     app_client <- n_crud: Err.NotFound
   else False
     app_client <- n_crud: Err.NotAuthorized
   else True
     n_crud --> n_crud: Log(READ)
     n_crud -> n_ostore: getSystemMetadata(PID)
     n_crud <- n_ostore: bytes
     app_client <- n_crud: bytes
     deactivate n_crud
   end
   deactivate app_client
   @enduml

.. image::  images/36_seq.png

*Figure 2.* Sequence diagram for Use Case 37 illustrating the sequence for
retrieving the system metadata for an object identified by PID from a
Coordinating Node.

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