Page History

...

<select name="identifier_qualifier_0">
    <option VALUE="govdoc">Gov't Doc #</option>
    <option VALUE="uri">URI</option>
    <option VALUE="isbn">ISBN</option>
</select>

Modifying metadata form presented for Bitstreams

...

Deploying Your Custom Forms

The DSpace web application only reads your custom form definitions when it starts up, so it is important to remember:

• You must always restart Tomcat (or whatever servlet container you are using) for changes made to the submission-forms.xml

...

<form-definitions>
    <!-- Form used for entering in Bitstream/File metadata after uploading a file -->
    <form name="bitstream-metadata">
        ...
    </form>
</form-definitions>

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

After uploading a file (bitstream) in the Submission UI, you can optionally edit that bitstream's access conditions.  This allows you to embargo a bitstream, lease it, or limit it to Administrators only.

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

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

...

• and/or item-submission.xml to take effect.

Any mistake in the syntax or semantics of the form definitions, such as poorly formed XML or a reference to a nonexistent field name, may result in errors in the DSpace REST API & UI. The exception message (at the top of the stack trace in the dspace.log file) usually has a concise and helpful explanation of what went wrong. Don't forget to stop and restart the servlet container before testing your fix to a bug.

Configuring the File Upload step

Basic Settings

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

• upload.max- The maximum size of a file (in bytes) that can be uploaded from the UI. It defaults to 536870912 bytes (512MB). You may set this to -1 to disable any file size limitation.
  • Note: Increasing this value or setting to -1 does not guarantee that DSpace will be able to successfully upload larger files via the web, as large uploads depend on many other factors including bandwidth, web server settings, internet connection speed, etc.
• webui.submit.upload.required - Whether or not all users are required to upload a file when they submit an item to DSpace. It defaults to 'true'. When set to 'false' users will see an option to skip the upload step when they submit a new item.

Modifying metadata form presented for Bitstreams

After uploading a file (bitstream) in the Submission UI, you can optionally edit that bitstream's metadata.  The form displayed on that edit screen is built by the "bitstream-metadata" form defined in submission-forms.xml.  You can modify that form to change the fields captured for a Bitstream.  However, the "dc.title" field is REQUIRED in order to store the name of the file.

<form-definitions>
    <!-- Form used for entering in Bitstream/File metadata after uploading a file -->
    <form name="bitstream-metadata"

...

>
        

...

...
    </

...

form>
</form-definitions>

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

After uploading a file (bitstream) in the Submission UI, you can optionally edit that bitstream's access conditions.  This allows you to embargo a bitstream, lease it, or limit it to Administrators only.

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

• 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): 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.
  • 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, 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, 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="

  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): 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.
  • 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, 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, 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="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 (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 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)
  • "embargo" - embargoes the bitstream for a period of time (maximum of 3 years, as defined in startDateLimit default setting), after which it becomes anonymously accessible.
  • "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)

Deploying Your Custom Forms

The DSpace web application only reads your custom form definitions when it starts up, so it is important to remember:

• You must always restart Tomcat (or whatever servlet container you are using) for changes made to the submission-forms.xml and/or item-submission.xml to take effect.

Any mistake in the syntax or semantics of the form definitions, such as poorly formed XML or a reference to a nonexistent field name, may result in errors in the DSpace REST API & UI. The exception message (at the top of the stack trace in the dspace.log file) usually has a concise and helpful explanation of what went wrong. Don't forget to stop and restart the servlet container before testing your fix to a bug.

Configuring the File Upload step

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

• comes with three 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)
  • "embargo" - embargoes the bitstream for a period of time (maximum of 3 years, as defined in startDateLimit default setting), after which it becomes anonymously accessible.
  • "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)
• upload.max- The maximum size of a file (in bytes) that can be uploaded from the UI. It defaults to 536870912 bytes (512MB). You may set this to -1 to disable any file size limitation.
  • Note: Increasing this value or setting to -1 does not guarantee that DSpace will be able to successfully upload larger files via the web, as large uploads depend on many other factors including bandwidth, web server settings, internet connection speed, etc.
• webui.submit.upload.required - Whether or not all users are required to upload a file when they submit an item to DSpace. It defaults to 'true'. When set to 'false' users will see an option to skip the upload step when they submit a new item.

Creating new Submission Steps Programmatically.

...