Page History

...

This preference is stored in the dspace.cfg value webui.submission.restrictstep.enableAdvancedForm.  If not set, the default is for Simple Embargo.

...

• Edit Item
• Edit Bitstream
• Wildcard Policy Admin Tool

Configuring and using Embargo

...

in DSpace 3.0+

Introduction

The following sections describe the steps needed to configure and use the new Embargo functionality in DSpace 3.0.

...

As a first step, the following script needs to be executed to ensure that your DSpace database gets extended with 3 new fields, required by the new embargo.  This is part of the normal process of upgrading from DSpace 1.8.x to 3.0.

 - dspace/etc/[postgres-oracle]/database_schema_18-3.sql

...

To enable the new embargo, changes are required to the item-submission.xml file, located in your config directory. This file determines which steps are executed in the submission of a new item.

...

• AccessStep: the step in which the user can set the embargo at item level, effectively restricting access to the item metadata.
• UploadWithEmbargoStep: the step in which the user can set the embargo at bitstream level. If this step is enabled, the old UploadStep must be disabled, leaving .  Leaving both steps enabled will result in a system failure.

...

To enable the new Embargo, ensure that the new steps are uncommented , while and the old UploadStep needs to be is commented out.

Simple Embargo Settings

Using the simple embargo settings, submitters will be able to define embargoes bound to specific dates, that are applied to all anonymous and default read access. To keep the interface simple, options to apply embargoes for particular groups of DSpace users are not shown. The simple embargo settings interface assumes that embargoes always start immediately upon submission, so only end dates are configurable.

...

• Private item: to hide an item's metadata from all search and browse indexes, as well as external interfaces such as OAI-PMH.
• Embargo Access until Specific Date: to indicate a date until when which the item will be embargoed.
• Reason: to elaborate on the specific reason why an item is under embargo.

When Embargo is set, it applies to Anonymous or to any other Group that is indicated to have default read access for that specific collection.

...

• Embargo Access until Specific Date: to indicate a date until when which the bitstream will be embargoed. When left empty, no embargo will be applied.
• Reason: to elaborate on the specific reason why the bitstream is under embargo.

...

The Advanced Embargo settings are really designed with a submitter in mind who is aware of user groups in DSpace and has notions understanding of the way how Resource Policies work.

AccessStep

The Advanced AccessStep Embargo step allows the users to manage more fine-grained resource policies to attach to the item.

...

• Policies List: list of the custom policies already added.
• Private Item: whether to hide an item's metadata from all search and browse indexes, as well as external interfaces such as OAI-PMH.
• Name: to give a name to the policy.
• Groups: to indicate the group for user groups to which the policy will apply to.
• Visible/Embargoed: to set if whether the Item will be visible or embargoed for that specific group.
• Embargo Access until Specific Date: to indicate a date until which the item will be embargoed.
• Reason: to elaborate on the specific reason why the policy is applied.

Last The last two fields will be enabled only in case of when Embargoed has been selected.

This step gives the opportunity to the user to manage the policy manually, so that combination combinations such as the following will be possible:

• Set Embargo for Anonymous
• Set Embargo for anyone, except for the users belonging to a specific group
• Set Embargo for specific groups, but not for another other groups ...

Here is a screenshot of the Access step form that will be rendered for the advanced embargo settings:

...

UploadWithEmbargoStep for Advanced Embargo settings displays an additional Policies button next to Edit in the list of uploaded files.
Clicking it brings you to the a page where you can edit existing policies on the bitstream and add new ones.

When the button will be is pushed, a form similar to the one in the AccessStep will be render and makes rendered, making it possible to manage the policies at bitstream level.

...

Once a specific group is configured as supergroup here, only the groups belonging to the indicated group will be loaded in the selection dialogs. By default, all groups are loaded.

Private/Public Item

It is also possible to adjust the Private/Public state of an item also after it has been archived in the repository.

...

A migration routine has been developed to migrate the current Embargo to the new one.

To execute it occurs to , run the following command:

...

The following sections illustrate the technical changes that have been made to the back-end to add the new Advanced Embargo functionality.

ResourcePolicy

When the an embargo will be is set at item level or bitstream level, a new ResourcePolicy will be added.

...

• rpname: resource policy name
• rptype: resource policy type
• rpdescription: resource policy description

While rpname and rpdescription _rpdescription are fields manageable by the users, the _ rptype is a fields managed by the systemDSpace itself. It represents a type that a resource policy can assume beteween , among the following:

• TYPE_SUBMISSION: all the policies added automatically during the submission process
• TYPE_WORKFLOW: all the policies added automatically during the workflow stage
• TYPE_CUSTOM: all the custom policies added by users
• TYPE_INHERITED: all the policies inherited by the DSO fatherfrom the enclosing object (for Item, a Collection; for Bitstream, an Item).

Here is an example of all information contained in a single policy record:

...

To manage Private/Public state a new boolean attribute has been added to the Item:

• isDiscoverable

When and an Item is private, the attribute will assume the value false.

...

Some methods have been changed on AuthorizeManager _AuthorizeManager to manage  _ the new fields ans and some convenient convenience methods have been introduced like:

public static List<ResourcePolicy> findPoliciesByDSOAndType(Context c, DSpaceObject o, String type);
public static void removeAllPoliciesByDSOAndTypeNotEqualsTo(Context c, DSpaceObject o, String type);
public static boolean isAnIdenticalPolicyAlreadyInPlace(Context c, DSpaceObject o, ResourcePolicy rp);
public static ResourcePolicy createOrModifyPolicy(ResourcePolicy policy, Context context, String name, int idGroup, EPerson ePerson, Date embargoDate, int action, String reason, DSpaceObject dso);

...

Functionally, the embargo system allows you to attach '"terms' " to an item before it is placed into the repository, which express how the embargo should be applied. What do ' we mean by "terms' " here? They are really any expression that the system is capable of turning into (1) the time the embargo expires, and (2) a concrete set of access restrictions. Some examples:

"2020-09-12" - an absolute date (i.e. the date embargo will be lifted)
"6 months" - a time relative to when the item is accessioned
"forever" - an indefinite, or open-ended embargo
"local only until 2015" - both a time and an exception (public has no access until 2015, local users OK immediately)
"Nature Publishing Group standard" - look-up to a policy somewhere (typically 6 months)

These terms are ' interpreted ' by the embargo system to yield a specific date on which the embargo can be removed (or '"lifted'."), and a specific set of access policies. Obviously, some terms are easier to interpret than others (the absolute date really requires none at all), and the ' default ' embargo logic understands only the most basic terms (the first and third examples above). But as we will see below, the embargo system provides you with the ability to add in your own ' interpreters ' to cope with any terms expressions you wish to have. This date that is the result of the interpretation is stored with the item and the .  The embargo system detects when that date has passed, and removes the embargo ("lifts it"), so the item bitstreams become available. Here is a more detailed life-cycle for an embargoed item:

...

The first step in placing an embargo on an item is to attach (assign) '"terms' " to it.
  If these terms are missing, no embargo will be imposed. As we will see below, terms are carried in a configurable DSpace metadata field, so assigning terms just means assigning a value to a metadata field. This can be done in a web submission user interface form, in a SWORD deposit package, a batch import, etc. - anywhere metadata is passed to DSpace. The terms are not immediately acted upon, and may be revised, corrected, removed, etc, up until the next stage of the life-cycle. Thus a submitter could enter one value, and a collection editor replace it, and only the last value will be used. Since metadata fields are multivalued, theoretically there can be multiple terms values, but in the default implementation only one is recognized.

...

In DSpace terminology, when an Item has exited the last of any workflow steps (or if none have been defined for it), it is said to be '"installed' " into the repository. At this precise time, the ' interpretation ' of the terms occurs, and a computed '"lift date' " is assigned, which like the terms is recorded in a configurable metadata field. It is important to understand that this interpretation happens only once, (just like the installation), and cannot be revisited later. Thus, although an administrator can assign a new value to the metadata field holding the terms after the item has been installed, this will have no effect on the embargo, whose '"force' " now resides entirely in the '"lift date' " value. For this reason, you cannot embargo content already in your repository (at least using standard tools). The other action taken at installation time is the actual imposition of the embargo. The default behavior here is simply to remove the read policies on all the bundles and bitstreams except for the "LICENSE" or "METADATA" bundles. See the Extending embargo functionality section V. below for how to alter this behavior. Also note that since these policy changes occur before installation, there is no time during which embargoed content is '"exposed' " (accessible by non-administrators). The terms interpretation and imposition together are called '"setting' " the embargo, and the component that performs them both is called the embargo '"setter'".

Embargo period

After an embargoed item has been installed, the policy restrictions remain in effect until removed. This is not an automatic process, however: a '"lifter' " must be run periodically to look for items whose '"lift date' is past" has passed. Note that this means the effective removal of an embargo is does not occur on the lift date, but on the earliest date after the lift date that the lifter is run. Typically, a nightly cron-scheduled invocation of the lifter is more than adequate, given the granularity of embargo terms. Also note that during the embargo period, all metadata of the item remains visible.This default behavior can be changed. One final point to note is that the '"lift date'", although it was computed and assigned during the previous stage, is in the end a regular metadata field. That means, if there are extraordinary circumstances that require an administrator (or collection editor - anyone with edit permissions on metadata) to change the lift date, they this can do sobe done. Thus, they one can '"revise' " the lift date without reference to the original terms. This date will be checked the next
time the '"lifter' " is run. One could immediately lift the embargo by setting the lift date to the current day, or change it to '"forever' " to indefinitely postpone lifting.

...

When the lifter discovers an item whose lift date is in the past, it removes ("lifts") the embargo. The default behavior of the lifter is to add the resource policies
that would have been added had the embargo not been imposed. That is, it replicates the standard DSpace behavior, in which an item inherits it's its policies from its owning collection. As with all other parts of the embargo system, you may replace or extend the default behavior of the lifter (see section V. Extending embargo functionality below). You may wish, e.g., to send an email to an administrator or other interested parties , when an embargoed item becomes available.

...

After the embargo has been lifted, the item ceases to respond to any of the embargo life-cycle events. The values of the metadata fields reflect essentially historical or provenance values. With the exception of the additional metadata fields, they are the item is indistinguishable from items that were never subject to embargo.

...

DSpace embargoes utilize standard metadata fields to hold both the "terms" and the "lift date". Which fields you use are configurable, and no specific metadata element is dedicated or pre-defined for use in embargo. Rather, you must specify exactly what field you want the embargo system to examine when it needs to find the terms or assign the lift date.

...

You replace the placeholder values with real metadata field names. If you only need the "default" embargo behavior - which essentially accepts only absolute dates as "terms" ,
- this is the only configuration required, except as noted below.

There is also a property for the special date of '"forever'":

# string in terms field to indicate indefinite embargo
embargo.terms.open = forever

...

The default setter recognizes only two expressions of terms: either a literal, non-relative date in the fixed format "yyyy-mm-dd" (known as ISO 8601), or a special string used for open-ended embargo (the default configured value for this is '"forever'", but this can be changed in dspace.cfg to '"toujours'", '"unendlich'", etc). It will perform a minimal sanity check that the date is not in the past. Similarly, the default setter will only remove all read policies as noted above, rather than applying more nuanced rules (e.g allow access to certain IP groups, deny the rest). Fortunately, the setter class itself is configurable and you can '"plug in' " any behavior you like, provided it is written in java and conforms to the setter interface. The dspace.cfg property:

...