Page History

...

...

1. What is Versionable
   1. Versioning is at the level of an Individual Item
   2. 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. The Previous Versions Bitstreams are retained. If something was once retrievable, it is always retrievable.
3. 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.
4. 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.
5. 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.
6. 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, LNI and AIP packaging and be maintained in updates and restorations.

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, 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).

Services to support Versioning and Alternative Identifiers.

DSpace Item Versioning will be encapsulated as an Extensible Service that may be reimplemented by the local repository maintainers to produce alternate versioning behaviors and Identifier Schemes. Versioning Services layer on top of IdentifierServices dedicated to Encoding, Resolution, Minting and Registration of Identifiers for specific DSpace Items and Bitstreams.  It is through this highly extensible layering of functionality where local developers can alter the versioning behavior and introduce their own local enhancements.  The DSpace Service Manager, based on the Spring Framework, provides the key leverage for this flexibility.

Image Removed

Versioning Service

The Versioning Service will be responsible for the replication of one or more Items when a new version is requested.  The new version will not yet be preserved in the Repository, it will be preserved when the databases transactional window is completed, thus when errors arise in the versioning process, the database will be properly kept in its original state and the application will alert that an exception has occurred that is in need of correction.

The Versioning Service will rely on a generic IdentifierService that is described below for minting and registering any identifiers that are required to track the revision history of the Items.

public interface VersioningService {

    Version createNewVersion(Context c, int itemId);

    Version createNewVersion(Context c, int itemId, String summary);

    void removeVersion(Context c, int versionID);

    void removeVersion(Context c, Item item);

    Version getVersion(Context c, int versionID);

    Version restoreVersion(Context c, int versionID);

    Version restoreVersion(Context c, int versionID, String summary);

    VersionHistory findVersionHistory(Context c, int itemId);

    Version updateVersion(Context c, int itemId, String summary);

    Version getVersion(Context c, Item item);
}

Identifier Service

The Identifier Service maintains an extensible set of IdentifierProvider services that are responsible for two important activities in Identifier management:

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. The Bitstreams for previous versions are retained. If something was once retrievable, it should always be retrievable.
3. 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.
4. 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.
5. 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.
6. 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, LNI and AIP packaging and be maintained in updates and restorations.

User Interface

General behaviour: Linear Versioning

From the user interface, DSpace offers linear versioning. As opposed to hierarchical versioning, linear version has following properties:

• A new version can only be created started from the latest available version
• When new version has been created and still needs to pass certain steps of the workflow, it is temporary impossible to create another new version until the workflow steps are finished and the new version has replaced the previous one.

Creating a new version of an item

Administrators and collection/community administrators can create new versions of an item from the Item View page.

1. Click "Create a new version" from the Context Menu in the navigation bar.
2. Provide the reason for creating a new version that will lateron be stored and displayed in the version summary.
   
   Image Added
   
   
3. Your new version is now creates as a new Item in your Workspace. It requires you to go through the submission and workflow steps like you would do for a normal, new submission to the collection. The rationale behind this is that if you are adding new files or metadata, you will also need to accept the license for them. In addition to this, the versioning functionality does not bypass any quality control embedded in the workflow steps.
   
   Image Added 

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.

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).

Services to support Versioning and Alternative Identifiers.

DSpace Item Versioning will be encapsulated as an Extensible Service that may be reimplemented by the local repository maintainers to produce alternate versioning behaviors and Identifier Schemes. Versioning Services layer on top of IdentifierServices dedicated to Encoding, Resolution, Minting and Registration of Identifiers for specific DSpace Items and Bitstreams. It is through this highly extensible layering of functionality where local developers can alter the versioning behavior and introduce their own local enhancements.  The DSpace Service Manager, based on the Spring Framework, provides the key leverage for this flexibility.

Image Added

Versioning Service

The Versioning Service will be responsible for the replication of one or more Items when a new version is requested.  The new version will not yet be preserved in the Repository, it will be preserved when the databases transactional window is completed, thus when errors arise in the versioning process, the database will be properly kept in its original state and the application will alert that an exception has occurred that is in need of correction.

The Versioning Service will rely on a generic IdentifierService that is described below for minting and registering any identifiers that are required to track the revision history of the Items.

public interface VersioningService {

    Version createNewVersion(Context c, int itemId);

    Version createNewVersion(Context c, int itemId, String summary);

    void removeVersion(Context c, int versionID);

    void removeVersion(Context c, Item item);

    Version getVersion(Context c, int versionID);

    Version restoreVersion(Context c, int versionID);

    Version restoreVersion(Context c, int versionID, String summary);

    VersionHistory findVersionHistory(Context c, int itemId);

    Version updateVersion(Context c, int itemId, String summary);

    Version getVersion(Context c, Item item);
}

Identifier Service

The Identifier Service maintains an extensible set of IdentifierProvider services that are responsible for two important activities in Identifier management:

1. Resolution: IdentifierService act in a manner similar to the existing HandleManager in DSpace, allowing for resolution of DSpace Items from provided identifiers.
2. Minting: Minting is the act of reserving and returning an identifier that may be used with a specific DSpaceObject.

3. Registering: Registering is the act of recording the existence of a minted identifier with an external persistent resolver service, these services may reside on the local machine (HandleManager) or exist as external services (PURL or DEZID DOI registrations services)

   Code Block
   language java
   public interface IdentifierService { /**

4. Resolution: IdentifierService act in a manner similar to the exisitng HandleManager in DSpace, allowing for resolution of DSpace Items from provided identifiers.
5. Minting: Minting is the act of reserving and returning an identifier that may be used with a specific DSpaceObject.

6. Registering: Registering is the act of recording the existence of a minted identifier with an external persistent resolver service, these services may reside on the local machine (HandleManager) or exist as external services (PURL or DEZID DOI registrations services)

   Code Block

   public interface IdentifierService { /** * * @param context * @param dso * @param identifier * @return */ String lookup(Context context, DSpaceObject dso, Class<? extends Identifier> identifier); /** * * This will resolve a DSpaceObject based on a provided Identifier. The Service will interrogate the providers in * no particular order and return the first successful result discovered. If no resolution is successful, * the method will return null if no object is found. * * TODO: Verify null is returned. * * @param context * @param identifier * @return * @throws IdentifierNotFoundException * @throws IdentifierNotResolvableException */ DSpaceObject resolve(Context context, String identifier) throws IdentifierNotFoundException, IdentifierNotResolvableException; /** * * Reserves any identifiers necessary based on the capabilities of all providers in the service. * * @param context * @param dso * @throws org.dspace.authorize.AuthorizeException * @throws java.sql.SQLException * @throws IdentifierException */ void reserve(Context context, DSpaceObject dso) throws AuthorizeException, SQLException, IdentifierException; /** * * Used to Reserve a Specific Identifier (for example a Handle, hdl:1234.5/6) The provider is responsible for * Detecting and Processing the appropriate identifier, all Providers are interrogated, multiple providers * can process the same identifier. * * @param context * @param dso * @param identifier * @throws org.dspace.authorize.AuthorizeException @return */ String * @throws java.sql.SQLException * @throws IdentifierExceptionlookup(Context context, DSpaceObject dso, Class<? extends Identifier> identifier); /** * */ This will resolve voida reserve(Context context, DSpaceObject dso, String identifier) throws AuthorizeException, SQLException, IdentifierException; /**DSpaceObject based on a provided Identifier. The Service will interrogate the providers in * * @param context * @param dso no particular order and return the first successful result discovered. If no resolution is successful, * @return the method will return null * @throws org.dspace.authorize.AuthorizeExceptionif no object is found. * @throws java.sql.SQLException * TODO: Verify *null @throwsis IdentifierExceptionreturned. */ void* register(Context@param context, DSpaceObject dso) throws AuthorizeException,* SQLException,@param IdentifierException;identifier /** @return * @throws IdentifierNotFoundException * @throws IdentifierNotResolvableException Used to Register a*/ Specific Identifier (for exampleDSpaceObject aresolve(Context Handlecontext, hdl:1234.5/6) The provider is responsible forString identifier) throws IdentifierNotFoundException, IdentifierNotResolvableException; /** * Detecting and Processing the appropriate* identifier,Reserves allany Providersidentifiers arenecessary interrogated,based multipleon providers the capabilities of all providers * can processin the same identifierservice. * * @param context * @param dso * @param identifier * @return dso * @throws org.dspace.authorize.AuthorizeException * @throws java.sql.SQLException * @throws IdentifierException */ void registerreserve(Context context, DSpaceObject dso, String identifier) throws AuthorizeException, SQLException, IdentifierException; /**) throws AuthorizeException, SQLException, IdentifierException; /** * * Used to Reserve a Specific Identifier (for example a Handle, hdl:1234.5/6) The provider is responsible for * DeleteDetecting (Unbind)and allProcessing identifiersthe registeredappropriate foridentifier, aall specificProviders DSpaceare item.interrogated, Identifiers are "unbound" acrossmultiple providers * allcan providersprocess inthe nosame particular orderidentifier. * * @param context * @param dso * @param identifier * @throws org.dspace.authorize.AuthorizeException * @throws java.sql.SQLException.SQLException * @throws IdentifierException */ void reserve(Context context, DSpaceObject dso, String identifier) throws AuthorizeException, SQLException, IdentifierException; * @throws IdentifierException/** */ void* delete(Context@param context, DSpaceObject dso) throws AuthorizeException,* SQLException,@param IdentifierException;dso /** @return * Used to Delete a Specific Identifier (for example a Handle, hdl:1234.5/6) The provider is responsible for@throws org.dspace.authorize.AuthorizeException * @throws java.sql.SQLException * @throws IdentifierException */ Detecting and Processing thevoid appropriateregister(Context identifiercontext, allDSpaceObject Providersdso) arethrows interrogatedAuthorizeException, multiple providersSQLException, IdentifierException; * can process the same identifier./** * * @paramUsed context to Register a Specific Identifier * @param dso * @param identifier(for example a Handle, hdl:1234.5/6) The provider is responsible for * Detecting and @throws org.dspace.authorize.AuthorizeException * @throws java.sql.SQLExceptionProcessing the appropriate identifier, all Providers are interrogated, multiple providers * @throws IdentifierExceptioncan process the same identifier. */ void delete(Context * @param context, DSpaceObject dso, String* identifier)@param throwsdso AuthorizeException, SQLException, IdentifierException; }

Configuration

Enabling Versioning

To enable Versioning support is necessary to configure the aspect in the xmlui.xconf.

<aspect name="Versioning Aspect" path="resource://aspects/Versioning/" />

VersioningService and IdentifierService

Two configuration files are deployed under the dspace installation directory to configure/override the default behavior of VersioningService and IdentifierService:

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

versioning-service.xml:

1. * @param identifier * @return * @throws org.dspace.authorize.AuthorizeException * @throws java.sql.SQLException * @throws IdentifierException */ void register(Context context, DSpaceObject dso, String identifier) throws AuthorizeException, SQLException, IdentifierException; /** * Delete (Unbind) all identifiers registered for a specific DSpace item. Identifiers are "unbound" across * all providers in no particular order. * * @param context * @param dso * @throws org.dspace.authorize.AuthorizeException * @throws java.sql.SQLException * @throws IdentifierException */ void delete(Context context, DSpaceObject dso) throws AuthorizeException, SQLException, IdentifierException; /** * Used to Delete a Specific Identifier (for example a Handle, hdl:1234.5/6) The provider is responsible for * Detecting and Processing the appropriate identifier, all Providers are interrogated, multiple providers * can process the same identifier. * * @param context * @param dso * @param identifier * @throws org.dspace.authorize.AuthorizeException * @throws java.sql.SQLException * @throws IdentifierException */ void delete(Context context, DSpaceObject dso, String identifier) throws AuthorizeException, SQLException, IdentifierException; }

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. -->

<?xml version="1.0" encoding="UTF-8"?>
<!--

    Copyright (c) 2002-2010, DuraSpace.  All rights reserved
    Licensed under the DuraSpace License.

    A copy of the DuraSpace License has been included in this
    distribution and is available at: http://www.dspace.org/license

-->
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://www.springframework.org/schema/beans
           http://www.springframework.org/schema/beans/spring-beans-2.5.xsd">


    <!-- Versioning Service Application Interface for DSpace Will be autowired with
         a Versioning Provider present in Spring context.
         Default Item Versioning Provider, defines behavior for replicating
         Item, Metadata, BUndles and Bitstreams. Autowired at this time.

    <bean id="org.dspace.versioning.VersioningService"
          class="org.dspace.versioning.VersioningServiceImpl"
          autowire="byType"
          scope="singleton">
        <property name="versionDAO">
            <bean class="org.dspace.versioning.VersionDAO"/>
        </property>
        <property name="versionHistoryDAO">
            <bean class="org.dspace.versioning.VersionHistoryDAODefaultItemVersionProvider"/>
        </property>
        <property name="provider">

            <bean class="org.dspace.versioning.DefaultItemVersionProvider"/>
="ignoredMetadataFields">
         </property>

<set>
       </bean>
     -->
</beans>

identifier-service.xml:

<?xml version="1.0" encoding="UTF-8"?>
<!--

Copyright (c) 2002-2010, DuraSpace. All rights reserved
Licensed under the DuraSpace License.

A copy of the DuraSpace License has been included in this
distribution and is available at: http://www.dspace.org/license

-->
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans-2.5.xsd">

<!-- Identifier Service Application Interface. Will be autowired with
any Identifier Providers present in Spring context.
-->
<bean id="org.dspace.identifier.IdentifierService"
class="org.dspace.identifier.IdentifierServiceImpl"
autowire="byType"
scope="singleton"/>

<!-- provider for using the versioned handle identifier instead of the default one. -->
<!-<bean id="org.dspace.identifier.HandleIdentifierProvider" class="org.dspace.identifier.VersionedHandleIdentifierProvider"->
<!-scope="singleton">->
<!-<property name="configurationService" ref="org.dspace.services.ConfigurationService"/>->
<!-</bean>->

</beans>

To enable VersionedHandleIdentifierProvider reinstate it taking off the comment.
VersionedHandleIdentifierProvider will attach the revision number at the end of the item identifier for e.g., the version 3 of the item 12345/123 will be 12345/123.3.

Enable VersionHistory only for Administrator

To set the version history to be seen only by the administrators a property in the versioning.cfg file can be edited:

item.history.view.admin=false

User Interface

Create a new version of an item

To create a new version of an existing item the following steps have to be performed:

1. Search for an Item
2. Go to Item view page
3. click on "create a new version"
4. fill out the form and confirm the operation 

. Image Removed

After the operation is confirmed a new submission process will be generated and the user could modify the metadata and the bitstream(s).
The new version of the item won't be visible until the workflow will be completed.

Access history of an item

To access the history of an item the following steps have to be performed:

...

<value>dc.date.accessioned</value>
            <value>dc.description.provenance</value>
         </set>
    </property>
</bean>

Identifier Service Override

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 Added

By default, all users will be able to see the version history. To ensure that only administrators can see the Version History, enable item.history.view.admin in following configuration file:

[dspace_installation_dir]/config/modules/versioning.cfg

item.history.view.admin=false

Identified Challenges & Known Issues in DSpace 3.0

Item Level Versioning has a substantial conceptual impact on many DSpace features. Therefore it has been accepted into DSpace 3.0 as an optional feature. Following challenges have been identified in the current implementation. As an early adopter of the Item Level Versioning feature, your input is greatly appreciated on any of these.

Only Administrators and Collection/Community Administrators can add new versions

There is currently no configuration option to allow submitters to create new versions of an item. This functionality is restricted to Administrators and Collection/Community Administrators. In a context where original submission of DSpace items is done by non-administrator users, it might also make sense to allow them to create new versions. Especially given the fact that new versions have to pass through the workflow anyway.

Conceptual compatibility with Embargo

Lifting an embargo currently does not interact with Item Level Versioning. Additional implementation would be required to ensure that lifting an embargo actually creates a new version of the item. 

Conceptual compatibility with Item Level Statistics

Both on the level of pageviews and downloads, different versions of an item are treated as different items. As a result, an end user will have the impression that the stats are being "reset" once a new version is installed, because the previous downloads and pageviews are allocated to the previous version.

One possible solution would be to present an end user with aggregated statistics across all viewers, and give administrators the possibility to view statistics per version.

No support for JSP User Interface

Item Versioning in DSpace 3.0 was contributed without specific user interface support for JSP User Interface.

Exposing version history

The version history is added on the bottom of a versioned item page. A repository administrator can either decide to show this to all users, or restrict it to admins only. If it is shown to admins only, an end user will have no way to find the way to an older version. On the other hand, if a repository administrator does decide to expose version history to all users, the name and email address of the editor are exposed as well. This might actually be useful if the editor account is a generic institutional email address, but may conflict with local privacy laws if any personal details are included in this account.

Therefore, discussion has illustrated that there is a usecase for an intermediate exposure of version history that hides the Editor column.

You can join the discussion or contribute a new code here:
JIRA DS-1349 - Item Level Versioning exposes personal data 

Image Added

Credits

The initial contribution of Item Level Versioning to DSpace 3.0 was implemented by @mire with kind support from:

• MBLWHOI Library
• Woods Hole Oceanographic Institution
• Marine Biology Laboratory, Center for Library and Informatics, History and Philosophy of Science program
• Arizona State University, Center for Biology and Society
• Dryad

...