.. _UC04:

Use Case 04 - Create New Object
-------------------------------

.. index:: Use Case 04, UC04, create

Revisions
  View document revision history_.

Goal
  Create new content on a Member Node.

Summary
  A user adds new content to a Member Node (MN). The operation of adding new
  content to a Member Node is atomic to the Member Node, meaning there is no
  dependency on the replication or synchronization processes for the
  successful completion of a create operation.

  The metadata is retrieved by the CN using a pull mechanism (CN requests
  content from the MN) which may be triggered by a timer event or notification
  from the MN.

  The availability of new content on a MN is indicated by a flag in the
  response to a ping() message issued by a CN. The CN then retrieves a list of
  changes from the MN and for each change, retrieves the experiment metadata,
  stores it and generates a search metadata document by extracting content
  from the experiment metadata. The changes to the CN (stored experiment
  metadata, update search metadata) are replicated to the other CNs (Use Case
  ###). The CN schedules replication of the data package across other MNs
  (Use Case 06).


Actors
  Member Node, additional Member Nodes, Coordinating Nodes
  
  
Preconditions
  - Use is authenticated and so client application has an auth_token for the process.

  - DataONE system operational
  
  - MN is registered and is monitored
  
  
Triggers
  - New data package is present on Member Node
  
  - An existing data package is modified on a Member Node
  
  - A data package is deleted from a Member Node
 
 
Post Conditions
  - New data package is replicated across MNs
  
  - Search metadata is updated
  
  - Operation recorded in logs

  - CN update of search metadata

  - CN replication of metadata 

  - Watchers notified of change


**Notes**

- Are IDs are pegged to versions? If so, update might differ more radically
  from create.

- If delete is a metadata operation only, then will be very similar to update.
  But if it is a physical operation, it becomes more complex. Will there be an
  archival copy? Will member nodes that hold replicas be "forced" to destroy
  the replicas?

- Is submit from a member node a push or pull?

- Should queuing of a submission within a member node be required for success?
  (We assume yes, to guarantee replication of submissions).

- Can data packages be deleted or modified?

.. image:: images/04_uc.png

*Figure 1.* Use case 04.

.. image:: images/04_seq.png

*Figure 2.* Create, update, delete, science metadata or data object in Member 
Node.

.. 
   @startuml images/04_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. Create Object" as create
     usecase "06. MN Synchronize" as mn_sync
     client -- create
     CN -- create
     MN -- create
     create ..> author: <<includes>>
     create ..> authen: <<includes>>
     create ..> mn_sync: <<includes>>
   @enduml        


.. 
   @startuml images/04_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: create(auth_token, dataPackage)
   activate m_crud
   participant "CRUD API" as c_crud << Coordinating Node >>
     m_crud -> c_crud: validatePID(PID)
     m_crud <-- c_crud: PID
     m_crud -> m_crud: store()
   deactivate m_crud

   participant "State of Health API" as c_health << Coordinating Node >>
   c_health -> m_crud: ping()
   activate c_health
     c_health <-- m_crud: [ACK, NewData]
   participant "Synchronization API" as c_sync << Coordinating Node >>
     c_health -> c_sync: scheduleSynch(MN_ID)
   deactivate c_health
   @enduml

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