Warning: These documents are under active development and subject to change (version 2.1.0-beta).
The latest release documents are at: https://purl.dataone.org/architecture

Use Case 42 - Update System Metadata Properties

Goal

Alter mutable properties of System Metadata.

Summary

System Metadata provides low level information about each object in DataONE and inlcudes properties that are immutable and others that may be mutated by different agents.

This use case desribes the general pattern of updating System Metadata properties by agents with authority to do so.

In version 1.x of the DataONE infrastructure, System Metadata may only be altered through Coordinating Nodes (after creation and synchronization).

In version 2.x of the DataONE infrastructure, properties of System Metadata are managed by the Authoritative Member Node with the exception of Replica information, which is managed by the Coordinating Nodes. In version 2.x, the System Metadata serialVersion property is only updated by Coordinating Nodes during replication processing. Only the Authoritative Member Node can update dataSysMetadataModified.

Actors

  • A content owner
  • Coordinating Node
  • Member Node
  • Replication target Member Node

Preconditions

  • Object exists within the DataONE system

Triggers

  • A user or agent wishes to alter mutable properties of System Metadata for an object.

Post Conditions

  • The properties of System Metadata are altered
  • All replicas of System Metadata are in sync
  • Search indices are updated to reflect the change

Process

@startuml images/42_seq_a.png
autonumber
actor Bob
participant "Authoritative" as MN <<Member Node>>
participant "Coordinating Node" as CN <<Coordinating Node>>
participant "Replica" as MN_repl <<Member Node>>
note right of CN
  System Metadata
  Serial Version = 1
  dateSysMetadataModified = t1
end note
note right of MN
  System Metadata
  Serial Version = 1
  dateSysMetadataModified = t1
end note
note right of MN_repl
  System Metadata
  Serial Version = 1
  dateSysMetadataModified = t1
end note
Bob -> CN : Alter Property
activate CN
CN -> CN : update property\nserialVersion++\ndateSysMetadataModified = now()
note right of CN
  System Metadata
  Serial Version = 2
  dateSysMetadataModified = t2
end note
CN ->] : <<internal>> Notify System Metadata Changed
note right of CN
  Indexing and other CN services
  are notified of the change
end note
CN -> Bob: ack
deactivate CN

group Update All Member Nodes
CN -> MN: systemMetadataChanged
activate MN
CN->MN_repl: systemMetadataChanged
activate MN_repl
MN -> CN: getSystemMetadata
activate CN
CN -> MN: SystemMetadata
deactivate CN
MN -> MN : update property
note right of MN
  System Metadata
  Serial Version = 2
  dateSysMetadataModified = t2
end note
deactivate MN
MN_repl -> CN: getSystemMetadata
activate CN
CN -> MN_repl: SystemMetadata
deactivate CN
MN_repl -> MN_repl : update property
note right of MN_repl
  System Metadata
  Serial Version = 2
  dateSysMetadataModified = t2
end note
deactivate MN_repl
end
@enduml

Figure 2a. Sequence diagram for Use Case 42 illustrating the high level sequence of operations associated with altering system metadata of an object for version 1.x infrastructure where Coordinating Nodes are the authoritative source for System Metadata. In this scenario, user Bob updates properties of System Metadata (e.g. Access Policy) for an object, and that change is propogated to copies throughout the federation.

@startuml images/42_seq_b.png
autonumber
actor Bob
participant "Authoritative" as MN <<Member Node>>
participant "Coordinating Node" as CN <<Coordinating Node>>
participant "Replica" as MN_repl <<Member Node>>
Bob -> MN: getSystemMetadata
note right of MN
 System Metadata
 serialVersion = 10
 dateSysMetadataModified = t1
end note
note right of CN
 System Metadata
 serialVersion = 10
 dateSysMetadataModified = t1
end note
note right of MN_repl
 System Metadata
 serialVersion = 10
 dateSysMetadataModified = t1
end note
activate MN
MN -> Bob: dateSysMetadataModified = t1
deactivate MN
Bob -> MN : updateSystemMetadata\ndateSysMetadataModified=t1
activate MN
MN -> MN: check dateSysMetadataModified == t1
MN -> MN: update properties\ndateSysMetadataModified = now()
note right of MN
  System Metadata
  serialVersion = 10
  dateSysMetadataModified = t2

  Mutable properties other than Replica
  entries may be updated by a user
  with appropriate permission.
end note
MN -> CN: synchronize
activate CN
CN -> CN: schedule update
CN -> MN: ack
deactivate CN
MN -> Bob: ack
deactivate MN

... __Potentially long delay__ ...

CN -> MN : getSystemMetadata
activate CN
activate MN
MN -> CN: systemMetadata
deactivate MN
CN -> CN: update properties
note right of CN
 System Metadata
 serialVersion = 10
 dateSysMetadataModified = t2
end note
CN ->] : <<internal>> Notify System Metadata Changed
note right of CN
  Indexing and other CN services
  are notified of the change
end note

group Update only replica nodes
CN -> MN_repl: systemMetadataChanged
activate MN_repl
deactivate CN

MN_repl -> CN: getSystemMetadata
activate CN
CN -> MN_repl: SystemMetadata
deactivate CN
note right of MN_repl
 System Metadata
 serialVersion = 10
 dateSysMetadataModified = t2

 On replica MNs, all mutable System
 Metadata properties may be updated
 by a CN
end note
MN_repl -> MN_repl: update properties
deactivate MN_repl
end
@enduml

Figure 2b. Sequence diagram for Use Case 42 illustrating the high level sequence of operations associated with altering system metadata of an object for version 2.x infrastructure where Member Nodes are the authoritative source for System Metadata except for replication information (for which Coordinating Nodes are authoritative). In this scenario, user Bob updates properties of System Metadata (e.g. Access Policy) for an object, and that change is propogated to copies throughout the federation.