Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Improved clarity of Identifier Service Override section

...

Important warnings - read before enabling

 


Warning
titleAIP Backup & Restore functionality only works with the Latest Version of Items

If you are using the AIP Backup and Restore functionality to backup / restore / migrate DSpace Content, you must be aware that the "Item Level Versioning" feature is not yet compatible with AIP Backup & Restore. Using them together may result in accidental data loss.  Currently the AIPs that DSpace generates only store the latest version of an Item.  Therefore, past versions of Items will always be lost when you perform a restore / replace using AIP tools. See DS-1382.

Enabling Item Level Versioning

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

Info
Starting from DSpace 4.0, Item Level Versioning is also supported in JSPUI.

Steps for XML UI

...


Warning
titleDSpace 6 changed the way Handles are created for versioned Items

With version 6 the way DSpace crates Handles for versioned Items was changed. If you want to keep the old behavior of DSpace 4 and 5 you have to enable the VersionedHandleIdentifierProviderWithCanonicalHandles in the XML configuration files [dspace]/config/

...

spring/api/identifier-service.xml. See IdentifierServiceOverride below for details and the comments in the configuration file.

Enabling Item Level Versioning

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

Info
Starting from DSpace 4.0, Item Level Versioning is also supported in JSPUI.

Steps for XML

Code Block
<!-- =====================
     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):

Code Block
<!-- =====================
     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).

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

Initial Requirements

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 The Item Level Versioning implementation in DSpace 3.0 builds on following requirements identified by the stakeholders who supported this contribution: Initial Requirements Analysis

...

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:

Code Block
<!-- 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

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:

Code Block
<!-- 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 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 builded 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 Removed

The canonical handle will always point to the newest To stay with the example above, the first 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 the 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 by the example from above, the first version of an Item gets the Handle 10673/100, the second version 10673/100.2, the third version 10673.3 and so on. This strategy has the downside that there is no handle pointing always to the newest version. But each version gets an identifier that can be use to cite exactly this version. If page numbers changes 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 Removed

In DSpace 4 and 5 only the strategy using canoical handles (one handle that always points to the newest version) were implemented. In DSpace 6 the strategy of creating a new handle for each version was implemented. With DSpace 6 this new strategy become the default. The strategy using canonical handle still exists in DSpace but you have to change the configuration if you want to use it. 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).

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 Removed

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.

Code Block
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

...