Page History

...

Important warnings - read before enabling

Enabling Item Level Versioning

By default, Item Level Versioning is disabled in DSpace 3, 4, 5 and 6.

Steps for XML UI

...

...

Enabling Item Level Versioning

By default, Item Level Versioning is disabled in DSpace 3, 4, 5 and 6.

Steps for XML

<!-- =====================
     Item Level Versioning
     ===================== -->
<!-- To enable Item Level Versioning features, uncomment this aspect. -->
<aspect name="Versioning Aspect" path="resource://aspects/Versioning/" />

...

UI

If you wish to enable this feature, you just have to edit the versioning.enabled  settings in your uncomment the "Versioning" aspect in your [dspace]/config/modules/versioningxmlui.cfg file. Alternatively, you may override it in your local.cfg config (see Configuration Reference).xconf file (and restart your servlet container):

<!-- =====================
     Item Level Versioning
     ===================== -->
<!-- To enable Item Level Versioning features, uncomment this aspect. -->
<aspect name="Versioning Aspect" path="resource://aspects/Versioning/" />

Steps for JSP UI

If you wish to enable this feature, you just have to edit the versioning.enabled  settings in your [dspace]/config/modules/versioning.cfg file. Alternatively, you may override it in your local.cfg config (see Configuration Reference).

#

#---------------------------------------------------#
#------------ VERSIONING CONFIGURATIONS ------------#
#---------------------------------------------------#
#  These configs are used by the versioning system  #
#--------------#
#------------ VERSIONING CONFIGURATIONS ------------#
#---------------------------------------------------#
#Parameter# 'enabled' isThese configs are used only by JSPUI
versioning.enabled=false

Initial Requirements

The Item Level Versioning implementation in DSpace 3.0 builds on following requirements identified by the stakeholders who supported this contribution: Initial Requirements Analysis

 by the versioning system  #
#---------------------------------------------------#
#Parameter 'enabled' is used only by JSPUI
versioning.enabled=false

Initial Requirements

The Item Level Versioning implementation in DSpace 3.0 builds on following requirements identified by the stakeholders who supported this contribution: Initial Requirements Analysis

1. What should be Versionable
   
   1. Versioning happens at the level of an Individual Item
   2. Versioning should preserve the current state of metadata, bitstreams and resource policies attached to the item.
2. Access, Search and Discovery
   
   1. Only the most recent version of an item is available via the search interface
   2. Previous versions of Items should continue to be visible, citable and accessible 
3. What should be Versionable
   
   1. Versioning happens at the level of an Individual Item
   2. Versioning should preserve the current state of metadata, bitstreams and resource policies attached to the item.
4. Access, Search and Discovery
   
   1. Only the most recent version of an item is available via the search interface
   2. Previous versions of Items should continue to be visible, citable and accessible 
   3. The Bitstreams for previous versions are retained. If something was once retrievable, it should always be retrievable.
5. Identifiers
   
   1. Each version of an Item is represented by a separate "versioned" identifier
   2. A base "versionhistory" Identifier points to the most recent version of the Item. 
   3. A revision identifier also exists that is unique to the specific version.
   4. When a new version of an Item is deposited, a new revision identifier will be created.
6. Presentation
   
   1. On the item page, there is a link to view previous/subsequent versions.
   2. By examining the metadata or identifiers, it is possible to determine whether an item is the most recent version, the original version, or an intermediate version.
7. Access Control and Rights
   
   1. Certain roles should be able to generate a new version of the item via submission.
   2. To submitters, collection manager, administrators will be given to option to create new version of an  item.
   3. Rights to access a specific Item should transmute as well to previous versions
   4. Rights to access a specific Bitstream should also transmute to previous versions.
8. Data Integrity
   
   1. The relationships between versions should not be brittle and breakable by manipulating Item metadata records.
   2. The relationships between versions should be preserved and predictable in various Metadata Exports (OAI, Packagers, ItemExport)
   3. The relationships between versions should be maintained in SWORD and AIP packaging and be maintained in updates and restorations.

...

After the submission steps and the execution of subsequent workflow steps, the new version becomes available in the repository.

View the history and older versions of an item

An overview of the version history, including links to older versions of an item, is available at the bottom of an Item View page. The repository administrator can decide whether the version history should be available to all users or restricted to administrators. Since DSpace 6 the repository administrator can decide whether all users should be able to see the version submitter/editor or if this information is restricted and can be seen by administrators only. As this may expose data that my be considered personal (name and email address of the submitter), we encourage everyone to leave the default setting and reveal those information to administrators only.

Image Removed

Architecture

Versioning model

For every new Version a separate DSpace Item will be created that replicates the metadata, bundle and bitstream records. The bitstream records will point to the same file on the disk.

Image Removed

The Cleanup method has been modified to retain the file if another Bitstream record point to it (the dotted lines in the diagram represent a bitstream deleted in the new version), in other words the file will be deleted only if the Bitstream record processed is the only one to point to the file (count(INTERNAL_ID)=1).

Configuration

Versioning Service Override

You can override the default behaviour of the Versioning Service using following XML configuration file, deployed under your dspace installation directory:

[dspace_installation_dir]/config/spring/api/versioning-service.xml

In this file, you can specify which metadata fields are automatically "reset" (i.e. cleared out) during the creation of a new item version.  By default, all metadata values (and bitstreams) are copied over to the newly created version, with the exception of dc.date.accessioned and dc.description.provenance.  You may specify additional metadata fields to reset by adding them to the "ignoredMetadataFields" property in the "versioning-service.xml" file:

<!-- Default Item Versioning Provider, defines behavior for replicating
     Item, Metadata, Budles and Bitstreams. Autowired at this time. -->
<bean class="org.dspace.versioning.DefaultItemVersionProvider">
    <property name="ignoredMetadataFields">
         <set>
            <value>dc.date.accessioned</value>
            <value>dc.description.provenance</value>
         </set>
    </property>
</bean>

Identifier Service Override

Persistent Identifiers are used to address Items within DSpace. The handle system is deeply integrated within DSpace, but since DSpace 4 DOIs are supported as well. DSpace 4 and 5 supported one type of versioned handle: The initial version of an Item got a handle, e.g. 10673/100. When a newer version was created, this handle was moved to identify the newest version and the older got the same handle attached with an an dot and the version number. In the image below you see a version history of an item using this handle strategy. The idea behind this strategy is to use the Item Level Versioning to track metadata changes. Nevertheless you should manually ensure, that page numbers in Bitstreams are preserved to not invalidate any citations using the handle and a page number. The handle 10673/100 is called canonical handle as it is the handle canonically used by all versions of this item.

<include screenshot>

With DSpace 6.0 a new handle strategy was implemented and the default configuration from DSpace was changed to use this new strategy.

Beginning with version 6.0 DSpace supports two

You can override the default behaviour of the Identifier Service using following XML configuration file, deployed under your dspace installation directory:

[dspace_installation_dir]/config/spring/api/identifier-service.xml

No changes to this file are required to enable Versioning. This file is currently only relevant if you aim to develop your own implementation of versioning.

Version History Visibility

Image Removed

in the repository.

View the history and older versions of an item

An overview of the version history, including links to older versions of an item, is available at the bottom of an Item View page. The repository administrator can decide whether the version history should be available to all users or restricted to administrators. Since DSpace 6 the repository administrator can decide whether all users should be able to see the version submitter/editor or if this information is restricted and can be seen by administrators only. As this may expose data that my be considered personal (name and email address of the submitter), we encourage everyone to leave the default setting and reveal those information to administrators only.

Image Added

Architecture

Versioning model

For every new Version a separate DSpace Item will be created that replicates the metadata, bundle and bitstream records. The bitstream records will point to the same file on the disk.

Image Added

The Cleanup method has been modified to retain the file if another Bitstream record point to it (the dotted lines in the diagram represent a bitstream deleted in the new version), in other words the file will be deleted only if the Bitstream record processed is the only one to point to the file (count(INTERNAL_ID)=1).

Configuration

Versioning Service Override

You can override the default behaviour of the Versioning Service using following XML configuration file, deployed under your dspace installation directory:

[dspace_installation_dir]/config/spring/api/versioning-service.xml

In this file, you can specify which metadata fields are automatically "reset" (i.e. cleared out) during the creation of a new item version.  By default, all metadata values (and bitstreams) are copied over to the newly created version, with the exception of dc.date.accessioned and dc.description.provenance.  You may specify additional metadata fields to reset by adding them to the "ignoredMetadataFields" property in the "versioning-service.xml" file:

<!-- Default Item Versioning Provider, defines behavior for replicating
     Item, Metadata, Budles and Bitstreams. Autowired at this time. -->
<bean class="org.dspace.versioning.DefaultItemVersionProvider">
    <property name="ignoredMetadataFields">
         <set>
            <value>dc.date.accessioned</value>
            <value>dc.description.provenance</value>
         </set>
    </property>
</bean>

Identifier Service Override

Persistent Identifiers are used to address Items within DSpace. The handle system is deeply integrated within DSpace, but since version 4 DSpace can also mint DOIs. DSpace 4 and 5 supported one type of versioned handle: The initial version of an Item got a handle, e.g. 10673/100. This handle was called the canonical one. When a newer version was created, the canonical handle was moved to identify the newest version. The previously newest version got a new handle build out of the canonical handle extended by a dot and the version number. In the image below you see a version history of an item using this handle strategy.

Image Added

The canonical handle will always point to the newest version of an Item. This makes sense if you hide the version history. Normal users won't be able to find older versions and will always see just the newest one. Please keep in mind, that older versions can be accessed by "guessing" the versioned Handle if you do not remove the read policies manually. The downside of this identifier strategy is that there is no permanent handle to cite the currently newest version, as it will get a new Handle when a newer version is created.

With DSpace 6, versioned DOIs (using DataCite as DOI registration agency) were added and the default versioned Handle strategy was changed. Starting with DSpace 6, VersionedHandleIdentifierProvider creates a handle for the first version of an item. Every newer version gets the same handle extended by a dot and the version number. To stay with the example above, the first version of an Item gets the Handle 10673/100, the second version 10673/100.2, the third version 10673/100.3 and so on. This strategy has the downside that there is no handle always pointing to the newest version. But each version gets an identifier that can be use to cite exactly that version. If page numbers change in newer editions, the old citations stay valid. This strategy makes sense, especially if you present the version history to all users. In the image below you see a version history using this strategy.

Image Added

In DSpace 4 and 5, only the strategy using canonical handles (one handle that always points to the newest version) was implemented. In DSpace 6 the strategy of creating a new handle for each version was implemented and became the default. The strategy using the canonical handle still exists in DSpace but you have to enable VersionedHandleIdentifierWithCanonicalHandles in the file [dspace]/config/spring/api/identifier-serice.xml. With DSpace 6, versioned DOIs were introduced using the strategy that every new version gets a new DOI (extended by a dot and the version numbers for versions >= 2). To use versioned DOIs, you have to enable DOIs, use DataCite as the registration agency, and enable VersionedDOIIdentifierProvider in the named configuration file.

You can configure which persistent identifiers should be used by editing following XML configuration file, deployed under your dspace installation directory:

[dspace_installation_dir]/config/spring/api/identifier-service.xml

No changes to this file are required to enable Versioning. This file is currently only relevant if you want to keep the identifier strategy from DSpace 4 and 5 or if you want to enable DOIs or even versioned DOIs.

Version History Visibility

Image Added

By default, all users will be able to see the version history. To ensure that only administrators can see the Version History, enable versioning.item.history.view.admin in the [dspace]/config/modules/versioning.cfg OR in your local.cfg file.

versioning.item.history.view.admin=false

Allowing submitters to version their items (JSPUI only)

With DSpace 6.0 it became possible to allow submitters to create new versions of their own items. This currently works in JSPUI only and is switched off by default to keep the same behavior as XMLUI. The new versions are going through the normal workflow process if the collection is configured this way. To allow submitters to create new versions of Item they originally submitted, you have to change the configuration property versioning.submitterCanCreateNewVersion and set it to true.It is part of the configuration file By default, all users will be able to see the version history. To ensure that only administrators can see the Version History, enable versioning.item.history.view.admin in the [dspace]/config/modules/versioning.cfg OR but can be overridden in your local.cfg file.

...

too.

Identified Challenges & Known Issues in DSpace 4.0

...