.. _UC05:

Use Case 05 - Update Science Metadata
-------------------------------------

.. index:: Use Case 05, UC05, update

Revisions
  View document revision history_.

Goal
  Update or delete science metadata record on a Member Node.

Summary 
  Science metadata is immutable in DataONE. As such, modification involves
  generating a new science metadata record and indicating that the new record
  supersedes an existing record, and deletion involves deprecation so that the
  old metadata record is no longer visible during normal discovery and access.

  .. figure:: images/sketch_uc05_update.png

  *Figure 1.* Sketch of interactions involved in updating a science metadata
  object. An authenticated user calls the :func:`MN_crud.update` operation on
  a Member Node (A) with a new science metadata document and the identifier of
  the document being replaced. The update method sets the
  :attr:`SystemMetadata.obsoletedBy` property of the original document system
  metadata with the identifier of the new science metadata document (B), and
  the :attr:`SystemMetadata.obsoletes` property of the system metadata
  associated with the new science metadata is set to the identifier of the
  science metadata document being replaced (C). The Coordinating Nodes pick up
  the changes on the next Member Node synchronization (D). Changes are
  subsequently propagated to the replica locations.


Actors
  Member Node, additional Member Nodes, Coordinating Nodes

Preconditions
  - User is authenticated

  - MN is registered and is monitored

  - Science metadata being deleted / updated document exists  

Triggers
  - User calls :func:`MN_crud.update`

  - User calls :func:`MN_crud.delete`

Post Conditions
  - System metadata for science metadata object(s) updated

  - Replacement science metadata propagated through the system

  - Search indexes updated

  - Operation recorded in logs

  - Watchers notified of change


.. image:: images/05_uc.png

*Figure 2.* Use case 04.

.. image:: images/05_seq.png

*Figure 3.* Create, update, delete, search metadata or data object in Member
Node.


.. 
   @startuml images/05_uc.png
   actor "User" as client
   usecase "12. Authentication" as authen

   package "DataONE"
     actor "Coordinating Node" as CN
     actor "Member Node" as MN
     usecase "13. Authorization" as author
     usecase "04. Update Object" as update
     usecase "06. MN Synchronize" as mn_sync
     client -- update
     CN -- update
     MN -- update
     update ..> author: <<includes>>
     update ..> authen: <<includes>>
     update ..> mn_sync: <<includes>>
   @enduml

.. 
   @startuml images/05_seq.png
   Actor User
   participant "Client" as app_client << Application >>
   User -> app_client

   participant "CRUD API" as m_crud << Member Node >>
   app_client -> m_crud: update(token, obsoletedID, ID, scienceMetadata)
   activate m_crud
   participant "CRUD API" as c_crud << Coordinating Node >>
     m_crud -> c_crud: validatePID(token, ID)
     c_crud -> m_crud: OK
     m_crud -> m_crud: create(token, ID, scienceMetadata)
     m_crud -> m_crud: setObsolete(token, ID, obsoletedID)
     m_crud -> m_crud: store()
   m_crud -> app_client: OK
   deactivate m_crud
   @enduml

**Notes**

- Q. Are IDs are pegged to versions? If so, update might differ more radically
  from create. A. Yes. Create involves creation of a new science metadata
  object, update involves deprecating an existing science metadata document
  with a replacement, delete involves setting system metadata properties.

- Q. Should queuing of a submission within a member node be required for
  success? (We assume yes, to guarantee replication of submissions). A. No.
  Successful update is handled by the Member Node, if the new science metadata
  can be created and the system metadata can be updated, then the change
  should be considered complete. The Member Node synchronization process will
  ensure that the changes are propagated to the wider system.

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