.. _UC41:

Use Case 41 - Archive an Object
-------------------------------

.. index:: Use Case 41, archive, UC41

Revisions
~~~~~~~~~

View document revision history_.

Goal
~~~~

Archive an object so that it is no longer discoverable, but remains accessible
by those that already have a reference to it. Transition to an archived state
is not reversible.

Summary 
~~~~~~~

A content owner or manager would like to prevent further discovery of an 
object though ensure that references to the object (using its identifier) 
remain valid. 

Actors
~~~~~~

- Client, a content manager or owner (must have *write* permission)
- Coordinating Node
- Member Node

Preconditions 
~~~~~~~~~~~~~

- Client has authenticated to the desired level
- Client has write permission on the object
- Object has been synchronized by the Coordinating Nodes
- The object may be replicated to other Member Nodes

Triggers
~~~~~~~~

- A user with write permission calls :func:`CNCore.archive`


Post Conditions
~~~~~~~~~~~~~~~

- The *archive* property of :class:`Types.SystemMetadata` is set to "true"
- System metadata for all replicas of the object is updated
- Search indices are updated to remove the object

.. image:: images/41_uc.png


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


.. figure:: images/41_seq.png

*Figure 2.* Sequence diagram for Use Case 41 illustrating the high level 
sequence of operations associated with archiving an object.


Example
~~~~~~~

Using ``curl`` to archive an object::

  # The member node base URL
  MNODE="https://my.mn.org/base/url"

  # A client certificate with a subject that has write permission on the object
  CERT="my_client_certificate.pem"

  # The identifier of the object to be archived
  PID="object.identifier"

   # The identifier of the object to be archived. 
   PID="object.identifier"

   # The provided identifier must be properly URL path encoded
   EPID=URL_Encode(PID)   

   # Invoke the archive operation on the identifier
   curl -E ${CERT} -X PUT "$NODE/V1/archive/${EPID}"


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

     actor "Coordinating Node" as CN
     actor "Member Node" as MN
     usecase "13. Authorization" as author
     usecase "41. Archive Object" as archive
     usecase "06. MN Synchronization" as sync
     usecase "xx. Update replica metadata" as replup
     client -- archive
     CN -- archive
     MN -- archive
     archive ..> author: <<includes>>
     archive ..> authen: <<includes>>
     archive ..> sync: <<includes>>   
     sync ..-> replup: <<includes>>
   @enduml


.. 
   @startuml images/41_seq.png
   participant "Client" as app_client << Application >>
   participant "MN" as mn << Node >>
   participant "CN" as cn << Node >>
   participant "MN-replica" as mnr << Node >>
   app_client -> mn: MNStorage.archive(session, PID)
   mn -> mn: check write access on PID
   alt NotFound
     app_client <- mn: Err.NotFound
   else False
     app_client <- mn: Err.NotAuthorized
   else True
     mn -> mn: set System Metadata archive flag
     cn -> mn: Use Case 06, Synchronization
     cn -> mnr: MNAuthorization.systemMetadataChanged(PID)
   end
   @enduml


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