Page History

...

Important warnings - read before enabling

versioning.item.history.include.submitter=false

Enabling Item Level Versioning

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

...

If you wish to enable this feature, you just have to edit the   versioning.enabled  settings in your [dspace]/config/modules/versioning.cfg file (and restart your servlet container):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  #
#---------------------------------------------------#
#Parameter 'enabled' is used only by JSPUI
versioning.enabled=false

Initial Requirements

...

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 Removed

Architecture

Versioning model

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

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

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 EZID DOI registration services)

   Code Block
   language java
   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 * @throws java.sql.SQLException * @throws IdentifierException */ void reserve(Context context, DSpaceObject dso, String identifier) throws AuthorizeException, SQLException, IdentifierException; /** * * @param context * @param dso * @return * @throws org.dspace.authorize.AuthorizeException * @throws java.sql.SQLException * @throws IdentifierException */ void register(Context context, DSpaceObject dso) throws AuthorizeException, SQLException, IdentifierException; /** * * Used to Register 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 * @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. -->
<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

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

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

...

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 [dspace]/config/modules/versioning.cfg but can be overridden in your local.cfg too.

Identified Challenges & Known Issues in DSpace 4.0

...

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. For JSPUI Since DSpace 6 you can also configure if the submitter's name and email address should be part of the version history or if they should be hidden (see below). For XMLUI you currently do not have this choice and if the submitter's name and email address will be publicly exposed to everyone able to see should be part of the version history . This or if they should be hidden. To show the submitter might actually be useful if the editor account is always a generic institutional email address, but may conflict with local privacy laws if any personal details are included in this account. If you want to step in and enhance the XMLUI to respect the configuration option, please join the discussion here: JIRA DS-1349 - Item Level Versioning exposes personal dataaddress, but may conflict with local privacy laws if any personal details are included.

Hide Submitter details in

...

version table

 In either the file [dspace]/config/modules/versioning.cfg configuration file or your local.cfg, you can edit customize the configuration option versioning.item.history.include.submitter. By default this is set to false, which means that information about the submitter is only viewable by administrators. If you want to expose the submitters information to everyone (which be useful if all submitters uses generic institutional email addresses, but may conflict with local privacy laws if personla personal details are included) you can set this configuration property to true.

# The property item.history.include.submitter controls whether the name of
# the submitter of a version should be included in the version history of
# an item. This property is currently used in JSPUI only.
versioning.item.history.include.submitter=false

...

• 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

The JSP UI JSPUI compatibility has been added in DSpace 4.0 by CINECA