Versions
DROs, collections, and administrative policies (hereafter “objects”) may have 1 or more versions.
Versions represent changes to an object's files and cocina metadata over time. Versions are ordered, where that ordering is indicated by the version number.
In DSA, objects are implemented as the RepositoryObject model and versions as RepositoryObjectVersions. A RepositoryObject must have 1 or more RepositoryObjectVersions.
The RepositoryObjectVersion has attributes for storing the cocina metadata. Note that for legacy objects, the cocina metadata attributes will be null (since at the time of migration, cocina metadata from previous versions was not available).
An object is either in an open state or a closed state. When it is open, changes can be made to the object’s files and cocina metadata. When it is closed, changes should not be made to the object’s files and cocina metadata.
In DSA, a RepositoryObject is in the open state when its opened_version attribute is associated with a RepositoryObjectVersion, referred to as the opened version. The opened version can be considered a draft of changes to the object’s files and cocina metadata.
A RepositoryObject is in the closed state when its opened_version attribute is null.
The most recent RepositoryObjectVersion that has been closed and accessioned is referred to as the last closed version. The last closed version is associated with the RepositoryObject by the RepositoryObject’s last_closed_version attribute.
The head version is the open version if present, otherwise the last closed version. The head version is associated with the RepositoryObject by the RepositoryObject’s head_version attribute. This must be an attribute (rather than a derived property) so that we can query for current versions.
Opening a RepositoryObject involves making a duplicate of the last closed version, incrementing its version, and assigning it to the RepositoryObject’s opened_version attribute.
When an object is first created, it is open. Thus, a new RepositoryObject will have a RepositoryObjectVersion for version 1 associated with its opened_version attribute. It wil not be associated with any other RepositoryObjectVersions.
Applications should open an object by invoking DSA’s version open endpoint; within DSA, VersionService.open should be invoked.
Closing is initiated when a set of changes to the object’s files and cocina metadata is complete. After being closed, it is accessioned.
To close a RepositoryObject, the opened version is moved to the last closed version. Thus, the last_closed_version attribute is set and the opened_version is null.
Note that a RepositoryObject is closed before it is accessioned.
Applications should close an object by invoking DSA’s version close endpoint; within DSA, VersionService.close should be invoked.
Accessioning is the process of adding / updating an object in the repository (e.g., sending to the Preservation system, shelving / publishing to Access systems).
Accessioning should only be performed on a closed object. Accessioning must not change the object’s files or cocina metadata. An object should not be able to be opened while it is accessioning.
In the Workflow system, accessioning is performed by the accessionWF. An object is accessioning while the accessionWF is running.
Applications should initiate accessioning by invoking DSA’s version close endpoint; within DSA, VersionService.close should be invoked.
As noted above, an object’s files and cocina metadata can be changed when it is open to prepare it for accessioning. The process of preparing files and cocina metadata for accessioning is referred to as assembly.
A number of workflows assist with assembly. These include:
- assemblyWF
- gisAssemblyWF
- wasCrawlPreassemblyWF
- wasSeedPreassemblyWF
- ocrWF
An object is referred to as assembling when any of these workflows are running.
An object must be open while assembling. An object should not be closed or accessioning started while assembling.
Applications should initiate assembly by calling DSA’s (misnamed) accession endpoint.
Objects can have 0 or more user versions. A user version is a state of an object that is “tagged” by a user. User versions are displayed on PURL pages. The motivation for creating user versions is that users only want to make certain states of an object publicly available.
User versions are ordered, where that ordering is indicated by the version number.
In DSA, objects are implemented as the UserVersion model. A UserVersion is associated with a closed RepositoryObjectVersion.
