Versions Compared

Old Version 17

changes.mady.by.user Tim Donohue

Saved on

compared with

New Version 18

changes.mady.by.user Tim Donohue

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Add more docs on item access conditions

...

Configuring the File Upload step

Basic Settings

...

The

...

The Upload step in the DSpace submission process has a few configuration options which can be set with your [dspace]/config/local.cfg configuration file. They are as follows:

...

  • The "uploadConfigurationService" bean maps an existing "UploadConfiguration" bean (default is "uploadConfigurationDefault") to a specific step/section name used in item-submission.xml. 

    Code Block
    <!-- This default configuration says the <step-definition id="upload"> defined in item-submission.xml uses "uploadConfigurationDefault" -->
<bean id="uploadConfigurationService" class="org.dspace.submit.model.UploadConfigurationService">
    <property name="map">
        <map>
            <entry key="upload" value-ref="uploadConfigurationDefault" />
        </map>
    </property>
</bean>


  • One or more UploadConfiguration beans may exist, providing different options for different upload sections.  An "UploadConfiguration" consists of several properties:

    • name (Required): The unique name of this upload configuration

    • configurationService (Required): reference to the DSpace ConfigurationService (should always be "org.dspace.services.ConfigurationService").
    • metadata (Required): The metadata "form" to use for this upload configuration. The value specified here MUST correspond to a <form> defined in your submission-forms.xml.  In the below example, the "bitstream-metadata" form is used by the "uploadConfigurationDefault" bean...meaning that form will be used to capture metadata about the uploaded bitstream.
    • options (Required, but can be empty): list of all "AccessConditionOption" beans to enable. This list will be shown to the user to let them select which access restrictions to place on each bitstream. NOTE: To disable the ability to select bitstream access restrictions, comment out all <ref> tags to create an empty list of options.
    • maxSize: Optionally, you can specify a maximum size of file accepted by this UploadConfiguration.  If unspecified, default is to use "upload.max" in dspace.cfg/local.cfg, or have no maximum.

    • required: Optionally, you can specify if a file upload is required for this UploadConfiguration. If true, upload is required and users cannot complete a submission without uploading at least one file. If false, no upload is required to complete the submission. If unspecified, default is to use "webui.submit.upload.required" configuration in dspace.cfg/local.cfg, which defaults to "true" (file upload required).

      Code Block
      <bean id="uploadConfigurationDefault" class="org.dspace.submit.model.UploadConfiguration">
    <property name="name" value="upload"></property>
	<property name="configurationService" ref="org.dspace.services.ConfigurationService"/>
	<property name="metadata" value="bitstream-metadata" />
    <property name="options">
        <!-- This is the list of access options which will be displayed on the "bitstream-metadata" form -->
        <list>
            <ref bean=<!-- If no <ref> tags appear in this list, then access restrictions will not be allowed on bitstreams -->
        <list>
            <ref bean="openAccess"/>
            <ref bean="lease"/>
            <ref bean="embargoed" />
            <ref bean="administrator"/>
        </list>
    </property>
</bean>


  • Any number of "AccessConditionOption" beans may be added for applying different types of access permissions to uploaded files (based on which one the user selects). These beans are easy to add/update, and just require the following
    • ID id (Required): Each defined bean MUST have a unique "id" and have "class=org.dspace.submit.model.AccessConditionOption".
    • groupName: Optionally, define a specific DSpace Group which this Access Condition relates to.  This group will be saved to the ResourcePolicy when this access condition is applied.
    • name: Give a unique name for this Access Condition.  This name is stored in the ResourcePolicy "name" when this access condition is applied.
    • hasStartDate: If the access condition is time-based, you can decide whether a start date is required. (true = required start date, false = disabled/not required).  This start date will be saved to the ResourcePolicy when this access condition is applied.
    • startDateLimit: If the access condition is time-based, you can optionally set an start date limit (e.g. +36MONTHS). This field is used to set an upper limit to the start date based on the current date.  In other words, a value of "+36MONTHS" means that users cannot set a start date which is more than 3 years from today.  This setting's value uses Solr's Date Math Syntax, and is always based on today (NOW).
    • hasEndDate: If the access condition is time-based, you can enable/disable whether an end date is required. (true = required end date, false = disabled/not required).  This end date will be saved to the ResourcePolicy when this access condition is applied.

    • endDateLimit: If the access condition is time-based, you can optionally set an end date limit (e.g. +6MONTHS). This field is used to set an upper limit to the start date based on the current date.  In other words, a value of "+6MONTHS" means that users cannot set an end date which is more than 6 months from today.  This setting's value use Solr's Date Math Syntax, and is always based on today (NOW).

      Code Block
      <!-- Example access option named "embargo", which lets users specify a future date 
    (not more than 3 years from now) when this file will be available to Anonymous users -->
<bean id="embargoed" class="org.dspace.submit.model.AccessConditionOption">
        <property name="groupName" value="Anonymous"/>
        <property name="name" value="embargo"/>
        <property name="hasStartDate" value="true"/>
        <property name="startDateLimit" value="+36MONTHS"/>
        <property name="hasEndDate" value="false"/>  
</bean>


  • By default, DSpace comes with three these out-of-the-box Access Conditions (which you can customize/change based on local requirements)
    • "administrator" - access restricts the bitstream to the Administrator group immediately (after submission completes)
    • "openAccess" - makes the bitstream immediately accessible to Anonymous group (after submission completes)
    • "embargoembargoed" - embargoes the bitstream for a period of time (maximum of 3 years, as defined in startDateLimit default setting), after which it becomes anonymously accessible. See also Embargo for discussion of how embargoes work in DSpace.
    • "lease" - makes the bitstream anonymously accessible immediately (after submission completes), but that access expires  after a period of time (maximum of 6 months, as defined in endDateLimit default setting). After that date it is no longer accessible (except to Administrators)

Configuring the Item Access Conditions step

Enabling the step

By default, the "Item Access Conditions" step is disabled.  To enable it, simply update your item-submission.xml to include this tag in your <submission-process>:

Code Block
<submission-process name="traditional">
   ...
   
   <!-- This step enables embargoes and other access restrictions at the Item level -->
   <step id="itemAccessConditions"/>
</submission-process>

After making this update, you will need to restart your backend (REST API) for the changes to take effect.

Modifying access conditions (embargo, etc.) presented for Items

The "Item Access Conditions" step uses a similar access condition configuration as the "Upload" step as described in the Modifying access conditions (embargo, etc.) presented for Bitstreams documentation above.

All available Item access conditions are defined in a new Spring Bean configuration file [dspace]/config/spring/api/access-conditions.xml

  • One or more "AcccessConditionConfiguration" beans may exist, providing different options for different submission forms (only one should be in use in a form at a time).  By default an "accessConditionConfigurationDefault" bean is defined. An "AccessConditionConfiguration" consists of several properties:

    • name (Required): The unique name of this configuration. It must match the "id" of the step defined in your item-submission.xm

    • canChangeDiscoverable: Whether this configuration allows users to change the discoverability of an Item.  A "discoverable" item is one that is findable through all search/browse interfaces, provided that you have access to see that Item.  A "non-discoverable" item is one that will never be findable through search/browse (except by Administrators)... instead a direct link is necessary to view the Item.  See also DSpace Item State Definitions.  When "canChangeDiscoverable" is "true", the user can modify discoverability in this submission section. When set to "false", the user cannot modify this setting and all submitted Items will be "discoverable".

    • options (Required): list of all "AccessConditionOption" beans to enable for this Item access conditions step. This list will be shown to the user to let them select which access restrictions to place on this Item.
  • This step uses the same "AccessConditionOption" beans as the "Upload" step, as described in the Modifying access conditions (embargo, etc.) presented for Bitstreams documentation above.  You can choose to enable the same options for both Items and Bitstreams, or provide different options for each.
  • By default, DSpace comes with these out-of-the-box Access Conditions (which you can customize/change based on local requirements)
    • "administrator" - access restricts the bitstream to the Administrator group immediately (after submission completes)
    • "openAccess" - makes the bitstream immediately accessible to Anonymous group (after submission completes)
    • "embargoed" - embargoes the bitstream for a period of time (maximum of 3 years, as defined in startDateLimit default setting), after which it becomes anonymously accessible. See also Embargo for discussion of how embargoes work in DSpace.
    • "lease" - makes the bitstream anonymously accessible immediately (after submission completes), but that access expires after a period of time (maximum of 6 months, as defined in endDateLimit default setting). After that date it is no longer accessible (except to Administrators)

Examples of selecting Item and Bitstream access conditions

What happens when a User selects different access conditions for an Item (via the "Item Access Conditions" step) and its files (via the "Upload" step)?   Generally speaking, both

Generally speaking, both access restrictions will be applied.  Here's some examples:

  • If a user selects "openAccess" in the "Item Access Conditions" step AND "embargo" in the "Upload" step for one Bitstream
    • Then, the Item's metadata will be publicly visible, but that single Bitstream will be embargoed.
  • If a user selects "openAccess" in the "Item Access Conditions" step AND "administrator" in the "Upload" step for one Bitstream
    • Then, the Item's metadata will be publicly visible, but that single Bitstream will only be visible to Administrators
  • If a user selects "administrator" in the "Item Access Conditions" step AND nothing in the "Upload" step. 
    • Then, the Item's metadata and all Bitstreams will only be accessible to administrators.
  • If a user selects "embargo" in the "Item Access Conditions" step AND nothing in the "Upload" step. 
    • Then, the Item's metadata and all Bitstreams will be embargoed. Nothing will be visible in the system until the embargo data passes.
  • If a user selects "embargo" in the "Item Access Conditions" step AND "openAccess" in the "Upload" step for one Bitstream.
    • Then, the Item's metadata will be embargoed (making it impossible to find the Item unless you are an Administrator).  HOWEVER, the bitstream will be publicly accessible immediately (but only via a direct link, as it won't be searchable in the system until the embargo date passes).

Creating new Submission Steps Programmatically.

...