Installing the EUL Add-On (v0.2.1)

The following instructions will guide you through the installation of the various parts of the EUL-DSpace Add-On, depending on which parts you wish to use. The process is relatively simple, although at some points it is necessary to modify DSpace files in order to make the system work.

In order to make a clear distinction between your DSpace install and our Add-On source code, we will use the notation:

[eul] - The directory in which you have the unpacked EUL Add-On code.

[dspace] - Your target DSpace installation to add our code to.

This software has been tested for full compatibility with v1.1.1 of DSpace, and should also work with earlier versions.


1. Compulsory Installation Steps

This section explains how to install the parts of the system that are required before any of the subsequent facilities can be made to work. It does not matter if you are upgrading or installing from scratch for this section.

1.1.
Download and unpack the .tar.gz (available here) to the directory to which we will refer as [eul] from now on.

1.2.
Ensuring that ant is in the environment path, go to the [eul]/java directory and use the following command:

ant -Ddslib=[dspace]/lib

This will produce 1 warning regarding a deprecated method, which you should not worry about.

Next use the command:

ant -Ddslib=[dspace]/lib install

This will create an eul-dspace.jar file in the [dspace]/lib directory.

You now have all the compiled java installed that is required to run any of the following facilities.


2. Supervised WorkSpace

This section explains how to install the supervised workspace (see Documentation for more information). If you are upgrading from v0.1a or v0.2 you should go straight to 2.4 and continue.

2.1.
Ensuring that you are logged in as the dspace user, open a console to your dspace database with a command like:

psql dspace


2.2.
Once connected use the following SQL to create the database tables needed for this facility: 

CREATE SEQUENCE eulepersongroup2workspaceitem_seq;

CREATE TABLE EULepersongroup2workspaceitem (
	id integer DEFAULT nextval('EULepersongroup2workspaceitem_seq'),
	eperson_group_id integer,
	workspace_item_id integer,
	CONSTRAINT EULepersongroup2item_pkey PRIMARY KEY (id)
);

CREATE SEQUENCE eulworkspaceitemnotes_seq;

CREATE TABLE eulworkspaceitemnotes (
	note_id integer DEFAULT nextval('eulworkspaceitemnotes_seq'),
	item_id integer,
	note text,
	submitter_id integer,
	date_submitted timestamp without time zone,
	CONSTRAINT eulworkspaceitemnotes_pkey PRIMARY KEY (note_id)
);


2.3.
Disconnect from the database terminal using \q

2.4.
Go to [dspace]/jsp/WEB-INF/ and open up the file web.xml for editing. Under the relevant sections, enter the following code (Note that if upgrading from v0.1a or v0.2 you will only need to add the first servlet and the first servlet mapping as the rest of the entries should already be present): 

<!-- Servlets -->

<servlet>
    <servlet-name>eulworkspace</servlet-name>
    <servlet-class>ac.ed.dspace.EULWorkspaceServlet</servlet-class>
</servlet>

<servlet>
    <servlet-name>notes</servlet-name>
    <servlet-class>ac.ed.dspace.NotesServlet</servlet-class>
</servlet>

<servlet>
    <servlet-name>supervise</servlet-name>
    <servlet-class>ac.ed.dspace.SuperviseServlet</servlet-class>
</servlet>

<servlet>
    <servlet-name>view-workspaceitem</servlet-name>
    <servlet-class>ac.ed.dspace.ViewWorkspaceItemServlet</servlet-class>
</servlet>


<!-- Servlet Mappings -->

<servlet-mapping>
    <servlet-name>eulworkspace</servlet-name>
    <url-pattern>/eulworkspace</url-pattern>
</servlet-mapping>

<servlet-mapping>
    <servlet-name>notes</servlet-name>
    <url-pattern>/notes</url-pattern>
</servlet-mapping>

<servlet-mapping>
    <servlet-name>supervise</servlet-name>
    <url-pattern>/admin/supervise</url-pattern>
</servlet-mapping>

<servlet-mapping>
    <servlet-name>view-workspaceitem</servlet-name>
    <url-pattern>/view-workspaceitem</url-pattern>
</servlet-mapping>


2.5.
Go into [eul]/jsp/new/workspace/ and copy all the JSPs here into the [dspace]/jsp/ directory. Note that the new files are directory structured in the same way as the corresponding JSPs in DSpace (so you may use a command like: cp -r * [dspace]/jsp). Note also that we do not use the [dspace]/jsp/local directory if possible since there are some bugs in the core code which can cause files here not to be picked up). If you are upgrading from v0.1a or v0.2 and have customised any of the jsps from these versions you should check that there will be no clashes by looking at the list of updated files at the end of this document.

2.6.
Go into [eul]/jsp/update/workspace/. If you still have the default installation of dspace, you may copy the JSPs here into [dspace]/jsp/ as per step (2.5). If not, you will need to open the JSPs in this directory and move the code delimited by:

******* Start EUL Code Inclusion ********
*************** WORKSPACE ***************

and

******* End EUL Code Inclusion ********

into the corresponding DSpace JSP.

At current release the only file here is mydspace/main.jsp, which is also used for the submission system, so if you are installing both you need simply to move this file. Otherwise you will need to strip out only code sections that you need.

If you are upgrading from v0.1a or v0.2 you should check the list of updated files to see if there is any necessity for you to update the files in this directory. Additional instructions are detailed in the files themselves. The updated files are directory structured in the same wayas the corresponding JSPs in DSpace. Some of the files may contain code for other facilities - these code snippents will be treated in exactly the same way when the facility is installed.

2.7.
If you are only installing this module go directly to section 5, otherwise go on to section 3.

3. Submission Interfaces

This module supports both the submission interface for a DSpace installation at a SHERPA (http://www.sherpa.ac.uk/) site and also the v1.0 of the submission interface for a UK recommended metadata set for E-theses. There is some pre- requisite installation and then there are 2 options for the install: both submission interfaces, with the option to choose between them based on submission type (3.6) or a single E-theses submission interface (3.5). If you are upgrading from v0.1a you need to follow this section in the same way as if you were installing from scratch. If you are upgrading from v0.2 you should go directly to 3.4 and continue.

3.1.
Ensuring that you are logged in as the dspace user, open a console to your dspace database with a command like:

psql dspace


3.2.
Once connected use the following SQL to create the database tables needed for this facility: 

CREATE SEQUENCE eulitem2submitengine_seq;

CREATE TABLE eulitem2submitengine (
	id integer DEFAULT nextval('eulitem2submitengine_seq'),
	item_id integer,
	submit_engine integer,
	CONSTRAINT eulitem2submitengine_pkey PRIMARY KEY (id)
);


3.3.
Disconnect from the database terminal using \q

3.4.
To ensure that both submission interfaces are supported by DSpace go to the Dublin Core Registry page in the admin area of your DSpace site and ensure that you have registered at least the following elements and qualifiers: 

contributor.advisor
contributor.author
contributor.editor
coverage.spatial
date.issued
date.verified
description.abstract
description.sponsorship
format.extent
format.mimetype
identifier.citation
identifier.govdoc
identifier.isbn
identifier.ismn
identifier.issn
identifier.uri
identifier
language.iso
publisher
relation.hasversion
relation.ispartof
relation.ispartofseries
relation.requires
relation.references
subject.ddc
subject.lcc
subject.lcsh
subject.mesh
subject.other
subject.udc
title.alternative
title
type

Obviously, if you have shut down Tomcat (and Apache) for this then it will have to wait until you have started them again - this does not need to be done until just before the next time either submission interface is used. There's a reminder at the end of this document so you don't forget to come back and finish this bit.

3.5.
Installing Only the E-theses submission system:-

If you wish only to provide an E-theses submission interface use the following instructions, otherwise move on to section 3.6. If you are upgrading from v0.2 and are continuing with only an E-Theses submission system you should go directly to 3.5.2 and continue.

It is also recommended that if using the E-theses submission sytem that you install the custom tags in section 4.

3.5.1.
Go to [dspace]/jsp/WEB-INF/ and open up the file web.xml for editing. Under the relevant sections, enter the following code (Note that we are updating an already existing servlet 'submit' as well as adding a new one): 

<!-- Servlets -->

<servlet>
    <servlet-name>submit</servlet-name>
    <servlet-class>ac.ed.dspace.GhostSubmitServlet</servlet-class>
</servlet>

<servlet>
    <servlet-name>theses-submit</servlet-name>
    <servlet-class>ac.ed.dspace.ThesesSubmitServlet</servlet-class>
</servlet>


<!-- Servlet Mappings -->

<servlet-mapping>
    <servlet-name>theses-submit</servlet-name>
    <url-pattern>/theses-submit</url-pattern>
</servlet-mapping>

Note: To remove the submission interfaces and return to default simply update the submit servlet record in web.xml with: 


<servlet>
		<servlet-name>submit</servlet-name>
    <servlet-class>org.dspace.app.webui.servlet.SubmitServlet</servlet-class>
</servlet>


3.5.2.
Go into [eul]/jsp/new/submission/ and copy the directory /theses-submit into the [dspace]/jsp/ directory. If you are upgrading from v0.2 and have made modifications to our jsps in your local installation you should check the list of updated files at the end of this document to ensure that there are no clashes.

3.5.3.
Go into [eul]/jsp/update/submission/. If you still have the default installation of dspace, you may copy the JSPs here into [dspace]/jsp/ as per step (3.5.2). If not, you will need to open the JSPs in this directory and move the code delimited by:

******* Start EUL Code Inclusion ********
*************** SUBMISSION **************

and

******* End EUL Code Inclusion ********

into the corresponding DSpace JSP. If you are upgrading from v0.2 you should check the list of updated files to see if there is any necessity for you to update the files in this directory. Additional instructions are detailed in the files themselves. The updated files are directory structured in the same way as the corresponding JSPs in DSpace. Some of the files may contain code for other facilities - these code snippents will be treated in exactly the same way when the facility is installed.

3.5.4.
If you are upgrading from v0.2 you should go to section 3.7. It is also recommended that you install the custom tags in section 4 if you have not already done so during installation of v0.2. Otherwise go straight to section 5.
3.6.
Installing both submission systems :-

This section will explain how to install both submission systems and the facility to choose between them depending on submission type. If you are upgrading from v0.2 and are continuing with a dual submission system you should go directly to section 3.6.2 and continue.

3.6.1
Go to [dspace]/jsp/WEB-INF/ and open up the file web.xml for editing. Under the relevant sections, enter the following code (Note that we are updating an already existing servlet 'submit' as well as adding a new one): 

<!-- Servlets -->

<servlet>
    <servlet-name>sherpa-submit</servlet-name>
    <servlet-class>ac.ed.dspace.SherpaSubmitServlet</servlet-class>
</servlet>

<servlet>
    <servlet-name>submit</servlet-name>
    <servlet-class>ac.ed.dspace.SelectSubmitServlet</servlet-class>
</servlet>

<servlet>
    <servlet-name>theses-submit</servlet-name>
    <servlet-class>ac.ed.dspace.ThesesSubmitServlet</servlet-class>
</servlet>


<!-- Servlet Mappings -->

<servlet-mapping>
    <servlet-name>sherpa-submit</servlet-name>
    <url-pattern>/sherpa-submit</url-pattern>
</servlet-mapping>

<servlet-mapping>
    <servlet-name>theses-submit</servlet-name>
    <url-pattern>/theses-submit</url-pattern>
</servlet-mapping>

Note: To remove the submission interfaces and return to default simply update the submit servlet record in web.xml with: 


<servlet>
    <servlet-name>submit</servlet-name>
    <servlet-class>org.dspace.app.webui.servlet.SubmitServlet</servlet-class>
</servlet>


3.6.2.
Go into [eul]/jsp/new/submission/ and copy all the JSPs here into the [dspace]/jsp/ directory. Note that the new files are directory structured in the same way as the corresponding JSPs in DSpace (so you may use a command like: cp -r * [dspace]/jsp). If you are upgrading from v0.2 and have made modifications to our jsps in your local installation you should check the list of updated files at the end of this document to ensure that there are no clashes.

3.6.3.
Go into [eul]/jsp/update/submission/. If you still have the default installation of dspace, you may copy the JSPs here into [dspace]/jsp/ as per step (3.6.2). If not, you will need to open the JSPs in this directory and move the code delimited by:

******* Start EUL Code Inclusion ********
*************** SUBMISSION **************

and

******* End EUL Code Inclusion ********

into the corresponding DSpace JSP.

At current release the only file here is mydspace/main.jsp, which is also used for the workspace, so if you are installing both you need simply to move this file. Otherwise you will need to strip out only code sections that you need.

If you are upgrading from v0.2 you should check the list of updated files to see if there is any necessity for you to update the files in this directory. Additional instructions are detailed in the files themselves. The updated files are directory structured in the same way as the corresponding JSPs in DSpace. Some of the files may contain code for other facilities - these code snippents will be treated in exactly the same way when the facility is installed.

3.6.4.
If you are upgrading from v0.2 you should go to section 3.7. It is also recommended that you install the custom tags in section 4 if you have not already done so during installation of v0.2. Otherwise go straight to section 5.
3.7.
To ensure that your database is consistent retrospectively with the new submission system for theses it is necessary to perform the following actions if upgrading from v0.2. If not you should go straight to section 4 or 5. These actions require that you have the QDC elements identifier.citation and relation.hasversion registered in your DSpace Dublin Core Registry (as per section 3.4). If you do not have these registered you should do so before executing the code below: there will be a reminder at the end of the document to come back and do this after you have restarted Tomcat (and Apache).

Ensuring that you are logged in as the dspace user, open a console to your dspace database with a command like:

psql dspace


3.8.
Once connected use the following SQL to update the qualified dublin core field that stores citations to parts of the thesis from its setting in v0.2 (identifier.citation) to the new recommendation in v0.2.1 (relation.hasversion): 

UPDATE dcvalue
SET dc_type_id = a.newnumber
FROM (
	SELECT dc_type_id AS newnumber
	FROM dctyperegistry
	WHERE element LIKE 'relation'
		AND qualifier LIKE 'hasversion'
) AS a
WHERE item_id IN (
	SELECT item_id
	FROM dcvalue
	WHERE text_value LIKE 'Thesis or Dissertation%'
	)
	AND dc_type_id = (
		SELECT dc_type_id
		FROM dctyperegistry
		WHERE element LIKE 'identifier'
			AND qualifier LIKE 'citation'
	);

4. Installing the Custom Tags

The custom tags improve the interface slightly for searching and browsing and also allow for the increased quantity of metadata being collected by the module installed in section 3 when viewing the item record. If you have not installed the submission module in section 3 then the custom tags are not so important, although you may still find them useful. If you are upgrading from v0.1a, or v0.2 (and did not install the custom tags at that time) you should to follow this section in the same way as if you were installing from scratch.

4.1.
Go to [dspace]/jsp/WEB-INF/ and open the file dspace-tags.tld for editing. Update the following tags with the new <tagclass> as shown below: 

<tag>
    <name>item</name>
    <tagclass>ac.ed.dspace.ItemTag</tagclass>
    ...
</tag>

<tag>
    <name>itemlist</name>
    <tagclass>ac.ed.dspace.ItemListTag</tagclass>
    ...
</tag>

Note: To uninstall the custom tags and revert to the original DSpace ones simply use: 

<tag>
    <name>item</name>
    <tagclass>org.dspace.app.webui.jsptag.ItemTag</tagclass>
    ...
</tag>

<tag>
    <name>itemlist</name>
    <tagclass>org.dspace.app.webui.jsptag.ItemListTag</tagclass>
    ...
</tag>


4.2.
Go to section 5.

5. Finalising the Installation

5.1.
Restart Apache and Tomcat. The installed modules should now work. See the Documentation for more information. It may be necessary to remove Tomcat's cached files, located in work/ in the Tomcat directory, to force the system to refresh.

5.2.
If you installed any submission systems, return to section 3.4 to check that you have the relevant dublin core elements registered with your system.

5.3.
If you have upgraded from v0.2 go to section 3.7 to ensure that your database is holding the correct data for theses.


Creating the JavaDocs

To create the Public API documentation for the EUL code, in the [eul] directory execute the following command:

ant public_api

This will build a directory: [eul]/public-api/ containing the documentation.



Updated Files Listing

This section documents the new or updated files since previous versions until the current one. This list should be consulted during upgrade to ensure that local modifications to files are not overwritten. Files that are new in the current version that did not exist in the version you are looking at the files for are under the sub-header "NEW", while files that have been updated in the current version that already existed in the version you are looking at the files for are under the sub-header "UPDATED".

Since the Beginning

NEW: 
choose-submit-engine.jsp
display-wsitem.jsp			
admin/supervise-link.jsp
admin/supervise-confirm-remove.jsp
admin/supervise-list.jsp
admin/supervise-main.jsp
admin/supervise-duplicate.jsp
eul-workspace/ws-error.jsp
eul-workspace/ws-main.jsp
notes/notes-add.jsp
notes/notes-error.jsp
notes/notes-main.jsp
sherpa-submit/*
theses-submit/*
UPDATED: 
layout/navbar-admin.jsp
mydspace/main.jsp
mydspace/perform-task.jsp
mydspace/preview-task.jsp
Since v0.1a

NEW: 
choose-submit-engine.jsp
admin/supervise-confirm-remove.jsp
eul-workspace/ws-error.jsp
eul-workspace/ws-main.jsp
sherpa-submit/*
theses-submit/*
UPDATED: 
admin/supervise-link.jsp
mydspace/main.jsp
mydspace/perform-task.jsp
mydspace/preview-task.jsp
notes/notes-main.jsp
Since v0.2

NEW: 
admin/supervise-confirm-remove.jsp
eul-workspace/ws-error.jsp
eul-workspace/ws-main.jsp
UPDATED: 
admin/supervise-link.jsp
mydspace/main.jsp
notes/notes-main.jsp
sherpa-submit/select-collection.jsp
theses-submit/edit-metadata-1.jsp
theses-submit/edit-metadata-2.jsp
theses-submit/review.jsp
theses-submit/select-collection.jsp