From DSpace Wiki

Configurable Submission Patch, Version 2.0

NOTE: This page is now out-of-date as it only contains information on the Older Configurable Submission patch, which only worked with the JSP user interface. A newer version of the Configurable Submission patch was recently committed to DSpace SVN and will be released as part of DSpace 1.5!

This page describes version 2.0 of the Configurable Submission patch (for JSP user interface ONLY). As mentioned in the above note, this version of the patch is outdated, as a new patch has been released on SourceForge (SF patch #1691345) which works with both the current JSP user interface and the upcoming Manakin user interface. (The new version of the patch also comes with its own documentation in the [dspace-source]/docs/submission.html file.)

For the time being, I've left this page as-is since version 2.0 of this patch (SF patch #1532695) is still more stable, even though it only works with the JSP UI.

For the absolute latest information, see the Current Status area at the bottom of this page.

Note: My presentation at the DSpace User Group meeting at OR 2007 is now available at http://hdl.handle.net/2142/207

As always, if there are any comments/suggestions, feel free to add them or email me - Tim Donohue (tdonohue <at> uiuc {dot} edu)

General Idea

The general idea is to make the Item Submission System more configurable for anyone installing and using DSpace. By "configurable", I am referring to creating an XML configuration file which will layout (1) the number of steps and (2) the ordering of the steps, for a particular installation of DSpace. In addition, you will be able to define different submission processes for different Collections within your DSpace installation.

How is this useful?

Currently (as of DSpace 1.4), DSpace comes with the following submission process (which is only configurable in terms of how many "Describe" pages you want):

(SelectCollection) -> InitialQuestions -> Describe -> Upload -> Verify -> License -> Complete

1) However, suppose you have decided at your institution that you'd like to have the following, simplistic 5-stage submission process (note the reordering of the same steps above, and removal of the "InitialQuestions" step):

(SelectCollection) -> License -> Describe -> Upload -> Verify -> Complete

2) In addition, you may want a particular Collection (e.g. a collection of Theses) to have its own custom submission process:

ThesisAgreement -> Describe -> Upload -> Verify -> OrderCopies -> Complete

Both #1 and #2 would be possible with this new Configurable Submission patch. In the case of #2, you'll notice that some custom "steps" (ThesisAgreement and OrderCopies) have been added into the process. This is to show off the fact that you will now be able to develop your own custom "steps" (assuming you are comfortable making your own Java class and JSPs).

This configuration can be controlled by the submission configuration file (described, in detail, below).

The Architecture

Overview

So far (as of DSpace 1.4), the entire submission process was always performed by a single Java "Submit" Servlet (org.dspace.app.webui.servlet.SubmitServlet). This servlet has started to become a little overwhelming, since it controls all the various "steps" during the submission process.

In the Configurable Submission patch, the entire submission process is now separated into it's various "Steps". Each "Step" should be as standalone as possible. As mentiond, in the current out-of-the-box DSpace (v. 1.4) there are a total of 6-7 steps (depending if SelectCollection is necessary), which appear in this order:

SelectCollection) -> InitialQuestions -> Describe -> Upload -> Verify -> License -> Complete

Each "Step" must define it's own Step class (which extends the new org.dspace.submit.step.SubmissionStep class, as described in the "Technical Specifics" below). Each step's class controls all the pre-processing and post-processing that takes place during that step, and decides which JSP (or JSPs) need to be displayed to the user.

In addition, a Step may consist of multiple "Pages" (by "Pages", I refer to the number of times a step will appear in the Progress Bar). The best example of this is the "Describe" (or metadata gathering) step in DSpace. The "Describe" step in DSpace 1.4 utilizes the "input-forms.xml" configuration file in order to determine how many metadata pages need to be shown to the user. Therefore, this Step may technically consist of one or more "Pages", depending on the number of pages defined in its "input-forms.xml" configuration file.

Some Technical Specifics (for JSP UI)

The general architecture of the Configurable Submission system is as follows:

• org.dspace.app.webui.servlet.SubmissionController - This is the "SubmissionController" servlet which replaces the old `org.dspace.app.webui.servlet.SubmitServlet`. This servlet reads the submission configuration file (using a few new utility classes), and controls all of the processing between the Steps in the submission process. This servlet also builds the Progress Bar, by asking each Step class how many Pages it has.

• org.dspace.submit.step.SubmissionStep - This class handles all processing within a Step. This class is important because all Step classes must extend this class! For example, for the "Describe" step, there is `org.dspace.submit.step.DescribeStep` which extends the `SubmissionStep`, and defines its own JSP, pre-processing (before JSP) and post-processing (after JSP). Overall, the SubmissionStep class includes the following important methods (those in bold are methods that must be defined for each Step class):
  • doPreProcessing() - performs any custom processing before a JSP is called. This usually includes gathering information to be displayed on the JSP & determining which JSP to call (which is especially important for multi-page steps)
  • showJSP() - load the specified JSP to show the current HTML page to the user
  • doPostProcessing() - performs any custom processing of the form information sent back by the JSP. This is where any code would go that stores the form information into database tables, uploads files, etc.
  • getNumberOfPages() - returns the number of "pages" within this step. Most steps may just return 1 (meaning they have one page).
  • getCurrentPage() - returns the number of the current page being shown. This is very useful for steps which have more than one page!

The Configuration File (for JSP UI)

The general format of the configuration file (named item-submission.xml) is as follows:

<item-submission>
   <!-- This is where you can map a particular Collection to a particular "Submission Process"-->
   <submission-map>
      <!--By default, a collection should used the "traditional" Submission Process-->
      <name-map collection-handle="default" submission-name="traditional" />
   </submission-map>

   <!--This is where external "step" definitions reside, which may be used by multiple submission-processes-->
   <step-definitions>
      <!--The special "Select Collection" step which is AUTOMATICALLY INCLUDED for every submission process as Step #0!-->
      <step id="collection">
        <heading></heading>
        <class-name>org.dspace.submit.step.SelectCollectionStep</class-name>
        <workflow-editable>false</workflow-editable>
      </step>

      <!--An "Initial Questions" step-->
      <step id="init">
       <heading>jsp.submit.progressbar.describe</heading>
       <class-name>org.dspace.submit.step.InitialQuestionsStep</class-name>
       <review-jsp>/submit/review-init.jsp</review-jsp>
       <workflow-editable>true</workflow-editable>
     </step>
   </step-definitions>

   <!--This is where you define each of your Submission Processes!-->
   <submission-definitions>
   
      <!--This "traditional" process defines the DEFAULT item submission process-->
      <submission-process name="traditional">
     
        <!--Step 1 will be to gather initial information (this refers back to the step defined in <step-definitions>)-->
        <step id="init"/>
     
        <!--Step 2 will be to Describe the item.-->
        <step>
          <heading>jsp.submit.progressbar.describe</heading>
          <class-name>org.dspace.submit.DescribeStep</class-name>
          <review-jsp>/submit/review-metadata.jsp</review-jsp>
          <workflow-editable>true</workflow-editable>
        </step>
     
        <!--Step 3 will be to Upload the item-->
        <step>
          <heading>jsp.submit.progressbar.upload</heading>
          <class-name>org.dspace.submit.step.UploadStep</class-name>
          <review-jsp>/submit/review-upload.jsp</review-jsp>
          <workflow-editable>true</workflow-editable>
        </step>

	 <!--Step 4 will be to Verify everything -->
	 <!--(this uses all the "review-jsp" tags set in the above steps to load the "Verify" page).-->
        <step>
          <heading>jsp.submit.progressbar.verify</heading>
          <class-name>org.dspace.submit.step.VerifyStep</class-name>
          <workflow-editable>true</workflow-editable>
        </step>

        <!--Step 5 will be to Sign off on the License-->
        <step>
          <heading>jsp.submit.progressbar.license</heading>
          <class-name>org.dspace.submit.step.LicenseStep</class-name>
          <workflow-editable>false</workflow-editable>
        </step>
      </submission-process>
  </submission-definitions>
</item-submission>

You'll notice some big similarities between this configuration file and the existing input-forms.xml configuration file. This is on purpose, in order to hopefully make it as straightforward as possible. However, also note it does not include the contents of the `input-forms.xml` configuration file, since input-forms.xml is considered to be a configuration file for the "Describe" step only.

The following is a general description of what each of the tags under the <step> tag refer to (bold tags are required):

• @id - If a <step> has an 'id' attribute, this means it refers back to the step with that ID within the <step-definitions> section.
• <heading> - Refers to the text in /config/language-packs/Message.properties which will be used as this step's "Heading" within the progress bar. You can also include free-text here, but it is recommended to refer to the Message.properties file, to keep all your text in one place. If the <heading> is not included, this step will not be displayed in the progress bar.
• <class-name> - Refers to the Step class which will actually perform this step. All Step classes must extend the `org.dspace.submit.step.SubmissionStep` class. For a sample step class (with internal notes and documentation) see the `org.dspace.submit.step.SampleStep` class. NOTE: The <class-name> tag has been renamed <processing-class> in the latest patch which works with both the JSP UI and Manakin!
• <review-jsp> - Refers to the "Review JSP" for this step, which displays a read-only view of the data gathered during this step. This JSP is loaded by the "Verify" step (org.dspace.submit.step.VerifyStep). This allows the "Verify" step to be dynamic, and allows it to work for any step that defines a simple "Review JSP". A sample Review JSP (with some internal notes and documentation) can be found at [dspace-source]/jsp/submit/sample-review.jsp.
• <workflow-editable> - Specifies whether or not this step is editable during any of the "Edit Metadata" stages within the Workflow process. If unspecified, this field defaults to true. If specified as false, this step will not even appear during the "Edit Metadata" stage of the Workflow process.

Further documentation for the syntax of the item-submission.xml can be found within the item-submission.xml itself (located at [dspace]/config/item-submission.xml, assuming you've downloaded and installed the Configurable Submission patch).

The Sample Step

Included within the patch is a sample custom step, which is hopefully a valuable reference when creating a new custom step. This sample step utilizes the following files:

• org.dspace.submit.step.SampleStep - This is the Step class which extends org.dspace.submit.step.SubmissionStep, and defines all the required methods, etc. It also has some comments in it to tell you how best to use the various required methods.
• [dspace-source]/jsp/submit/sample-step.jsp - This JSP is loaded by the org.dspace.submit.step.SampleStep class to just display some generic information to the user. This provides an example of how the Step class and Step JSP should interact.
• [dspace-source]/jsp/submit/sample-review.jsp - This JSP is the special "Review JSP" used for the Sample Step. It is loaded by the JSP for the VerifyStep (called `review.jsp`) whenever this sample step is used in the item-submission.xml config.

There is also a working entry for the Sample step within the item-submission.xml configuration file, in the <step-definitions> section. Here's a copy of the entry for your reference:

     <!-- This is the Sample Step which utilizes the SampleStep class-->
     <step id="sample">
            <heading>Sample</heading>
            <class-name>org.dspace.submit.step.SampleStep</class-name>
            <review-jsp>/submit/sample-review.jsp</review-jsp>
            <workflow-editable>true</workflow-editable>
     </step>

To see the Sample step in action, just add the following reference into your <submission-process> in the item-submission.xml (notice how it's id attribute references the step definition directly above):

     <step id="sample"/>

Creating a "Non-interactive" Step

The Configurable Item Submission patch also allows for the creation of "non-interactive" steps. A "non-interactive" step requires no user interaction, and therefore does not appear in the submission progress bar. Because they have no user interface, non-interactive steps also require no correspond JSP(s). For all intensive purposes you can think of a non-interactive step as one that just performs backend processing.

To create a non-interactive step, you would do the following:

1. Create a Step class as normal, which extends org.dspace.submit.step.SubmissionStep. Make sure this class does not call the showJSP() method, to display a JSP to the user. In addition, place all of your processing commands in the doPreProcessing() method (since doPostProcessing() is only called when you return from a JSP).
2. Create a step definition entry in the item-submission.xml configuration file. In the step definition entry only include the <class-name> tag to reference your Step class. A non-interactive step doesn't require any of the other configuration tags to function.

Here's an example entry for a "non-interactive" step in item-submission.xml:

     <!-- This is a non-interactive step which has no UI -->
     <step id="non-interactive-step">
            <class-name>edu.myedu.dspace.submit.step.NonInteractiveStep</class-name>
     </step>

In the above example, the NonInteractiveStep class's doPreProcessing() method will be called when the non-interactive step is reached in the submission process. Immediately after the doPreProcessing() method has completed its processing, the next step in the submission process will be called.

Installation of Patch

These are very brief instructions/hints on how to install the finished Configurable Item Submission patch. Note, this patch will only work in DSpace 1.4. The main reason is that it is dependent on the new Metadata Schema Registry code which was not included in DSpace 1.3.2 or previous versions.

1) Download patch (patch #1532695) from Source Forge. Unzip configurable_submission_2.0_patch.zip, and install the patch (using Eclipse or the linux 'patch' command) into your local DSpace 1.4 source code.

2) Update the 'workspaceitem' table in the database (this is taken from the database_schema_14-config_submission.sql within the patch):

-------------------------------------------------------------------------------
-- Necessary for Configurable Item Submission Patch:
-- Modification to workspaceitem table to support keeping track
-- of the last page reached within a step in the Configurable Item Submission Process
-------------------------------------------------------------------------------
ALTER TABLE workspaceitem ADD page_reached INTEGER;

3) Make a small update in the Messages.properties. In particular, make sure to copy these over this property: (again, this is in the patch)

jsp.submit.select-collection.no-collection =You must select a collection for this item.

4) Make sure to copy the [dspace-source]/config/item-submission.xml into your DSpace installation directory, [dspace]/config/

5) Recompile DSpace and build the new dspace.war. If something doesn't compile, chances are you are using a version of DSpace which will not work with this patch (or you've made customizations to DSpace 1.4 that cause the patch to not work properly).

6) Place the dspace.war the appropriate directory for your web server (e.g. [tomcat]/webapps for Tomcat), restart the web server, and you should be good to go!

Current Status

2007 Jul 20 - The Configurable Submission patch has been committed to SVN Trunk and will be released as part of DSpace 1.5. For More information on DSpace 1.5 see http://wiki.dspace.org/index.php/Next_Release_Status

2007 Mar 30 - A new version of the Configurable Submission patch has been released on SourceForge (SF patch #1691345). This version has been redesigned slightly to allow it to work with both the current DSpace JSP UI, and the upcoming Manakin XML UI. (The new version of the patch also comes with its own documentation in the [dspace-source]/docs/submission.html file.) As this is an "alpha" release, I'd appreciate anyone who can help with some testing. If you are looking for a more "stable" release, you still may wish to use the Version 2.0 of the patch (patch #1532695). But, this version only works with the JSP UI.

2007 Feb 1 - My presentation on the Configurable Submission System for the DSpace User Group meeting at Open Repositories 2007 (OR 2007) is now available at: http://hdl.handle.net/2142/207

2006 Dec 13 - Work is being done to modify this patch to also work with the Manakin XML-UI, in preparation to release it as part of DSpace 1.5 (alongside of Manakin). This integration may result in small changes to the above architecture (to allow it to work with both the current JSP UI and future XML-UI), but the overall goal is to remain mostly consistent with everything described above. If you have any questions about this integration, don't hesitate to contact me (Additionally, most discussion of these changes are taking place on the dspace-manakin listserv). - Tim Donohue

2006 Aug 1 - Version 2.0 of the patch is now available on SourceForge! The patch works on DSpace 1.4, and allows you to just create new Steps as classes (rather than as servlets, which version 1.0 required). It can be downloaded at patch #1532695. The old patch (#1409415) should no longer be used, and has been marked as "deleted" in SourceForge - Tim Donohue

2006 Jul 31 - Version 2.0 of the Configurable Submission patch is coming soon! This patch will work with DSpace 1.4, and be much more simplistic to use! - Tim Donohue

2006 Jan 18 - The full patch is complete! It can be downloaded from Source Forge as patch #1409415. As of 2006 Aug 1, this original patch is obsolete. Please use patch #1532695 instead.

2005 Dec 22 - Most of the architecture is already in place. However, there's still a few bugs in the paging mechanisms (back, next, jump-to-page) that are being worked out. The "SelectCollection" and "InitialQuestions" steps are relatively solid. The "Describe" step is currently being debugged. - Tim Donohue