#REDIRECT [[Upgrading 3.3.12+ to 3.4]]

2016-01-26T14:23:44Z

Jy2e08@ecs.soton.ac.uk: /* Troubleshooting */

[[Category:Bazaar Package]]

== Overview ==
The purpose of the Coversheets is to add a front and/or back covering page to a PDF document uploaded to an EPrints repository.

Coversheets work by using a user-defined [https://www.openoffice.org/ Apache OpenOffice] coversheet template uploaded to your EPrints repository. This template is then populated with the predefined attributes for the particular EPrint, before being attached to the front (or if specified, back) of any PDF documents uploaded for that EPrint. To do this a number of dependencies need to be installed:
* '''Ghostscript''' or '''PDFtk''': Either of these can be used to attach the coversheet to the rest of the PDF document.
* '''Apache OpenOffice''': This is used to open up the coversheet template, so that a coversheet for a particular EPrint can be created.
* '''Oracle (Sun) Java''': This is required to run the script to interact with OpenOffice and replace the templates tags with the appropriate EPrint attributes (title, authors, etc.).
* '''Perl Modules''': Needed for EPrints to interact with OpenOffice.

The instructions below provide guidance on testing and using the Coversheets Bazaar package on an EPrints 3.3 repository running on either Debian or RedHat based Linux distributions. These instructions are intended to be sufficiently generic to be interpreted for use when installing on other Linux distributions.

==Installing Dependencies==

===GhostScript or PDFtk===
The Coversheets Bazaar package requires either '''PDFtk''' or '''Ghostscript''' to attach the generated coversheet to the rest of the PDF document. For the more recent Linux distributions (e.g. Ubuntu 14.04, Debian 7 and RedHat/CentOS 7) Ghostscript is recommended as this is easier to install and more reliable, (e.g. it can reliably attach the coversheet without breaking the character encoding of the rest of the document, so you can still copy and paste out sections of the document). However, it may be less straightforward to get Ghostscript working for Coversheets on earlier distributions of Linux (e.g. pre Ubuntu 12.04 and RedHat/CentOS 6)

====Ghostscript====
Installing Ghostscript just requires a number of Linux packages. As root or with sudo run the appropriate following command:
* Debian/Ubuntu:
apt-get install ghostscript gsfonts gsfonts-other libgs9 libgs9-common
* RedHat/Fedora/CentOS:
yum install ghostscript ghostscript-devel ghostscript-fonts ghostscript-gtk

If you installed EPrints using the DEB or RPM package, it is likely many if not all of these packages will already be installed.

====PDFtk====
'''N.B. If you have already installed Ghostscript you do not need to install PDFtk as well.'''

As root or using sudo install '''gcj''', '''g++''' and '''make''' so you can compile '''pdftk'''.
* '''Debian/Ubuntu'''
apt-get install gcj-jdk g++ make
* '''RedHat/Fedora/CentOS'''
yum install gcc-java gcc-c++ make

Next, download and compile '''pdftk''' and deploy it in '''/usr/bin/'''.
* Substitute '''LinuxDist''' for '''Debian''' on Debian/Ubuntu distributions and '''Redhat''' for RedHat/Fedora/CentOS distributions.
* If you are using '''MakeFile.Debian''' check your version of gcj (gcj --version). You will then need to change '''VERSUFF''' in '''MakeFile.Debian''' to your version number but only the first two points of the version (e.g. 4.8.2 = 4.8).
wget https://www.pdflabs.com/tools/pdftk-the-pdf-toolkit/pdftk-2.02-src.zip
unzip pdftk-2.02-src.zip
cd pdftk-2.02-dist/pdftk
make -f Makefile.LinuxDist
mv pdftk /usr/bin/

===Oracle (Sun) Java===
Oracle (Sun) Java is required to make use of the Coversheets package. By default this is not available in the standard package repositories of most Linux distributions. Follow the instructions below (as the root user or with sudo) to install Oracle (Sun) Java on your Linux distribution:

* '''Debian/Ubuntu'''
apt-get install python-software-properties
add-apt-repository ppa:webupd8team/java
apt-get update
apt-get install oracle-java8-installer
* When prompted agree to the license agreement.

* '''RedHat/Fedora/CentOS'''
** Go to http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html and agree to the licence conditions.
** Download the appropriate .rpm package (i.e. i586 or x64) for you system architecture.
** Install the RPM from the command line, (substitute for '''<version>''' and '''<arch>''' based on the filename of the RPM you actually downloaded):
rpm -Uvh jdk-8u<version>-linux-<arch>.rpm

===Perl Modules===
Before installing the Perl modules make sure that '''make''' and '''gcc''' are installed as these are needed to build the OpenOffice Perl module. Run the appropriate command below as root or using sudo.
* '''Debian/Ubuntu'''
apt-get install make gcc
* '''RedHat/Fedora/Centos'''
yum install make gcc

As the root user install the following Perl modules using CPAN. Choose the default option for any prompted questions.
cpan ExtUtils::MakeMaker OpenOffice::OODoc PDF::API2 ADAMK/Archive-Zip-1.30.tar.gz

'''N.B.'''
# If you have not had to install any CPAN modules up to now ,you may be prompted to configure CPAN before installing these modules, if so always choose the default option provided.
# For Archive::Zip it is recommended to use the specific version 1.30 tarball (as specified above). CPAN will download this specific tarball as part of the installation, like it would for non-version specific modules. The reason for using this specific version is, that as of at least 28th April 2015 the latest CPAN module has a bug, which means it does not work as required for EPrints Coversheet purposes.

===Apache OpenOffice===
Download the tarballed package of OpenOffice 3.4.1 for your Linux distribution. Later and some earlier versions of OpenOffice should work just as well but 3.4.1 is tried and tested. Then extract your DEB or RPM packages and install as root (or with sudo) using '''dpkg''' or '''rpm''' as appropriate.

* Debian/Ubuntu (64-bit):
wget http://downloads.sourceforge.net/project/openofficeorg.mirror/stable/3.4.1/Apache_OpenOffice_incubating_3.4.1_Linux_x86-64_install-deb_en-US.tar.gz
tar -xzvf Apache_OpenOffice_incubating_3.4.1_Linux_x86-64_install-deb_en-US.tar.gz
mv en-US Apache_OpenOffice_incubating_3.4.1_Linux_x86-64_install-deb_en-US
dpkg -i Apache_OpenOffice_incubating_3.4.1_Linux_x86-64_install-deb_en-US/DEBS/*.deb

* RedHat/Fedora/CentOS (64-bit):
wget http://downloads.sourceforge.net/project/openofficeorg.mirror/stable/3.4.1/Apache_OpenOffice_incubating_3.4.1_Linux_x86-64_install-rpm_en-US.tar.gz
tar -xzvf Apache_OpenOffice_incubating_3.4.1_Linux_x86-64_install-rpm_en-US.tar.gz
mv en-US Apache_OpenOffice_incubating_3.4.1_Linux_x86-64_install-rpm_en-US
rpm -Uvh Apache_OpenOffice_incubating_3.4.1_Linux_x86-64_install-rpm_en-US/RPMS/*.rpm

* ''N.B. For 32-bit versions remove '-64' from each of the lines above.'' You can check this by running the following command. If it returns something with '64' in it, it is 64-bit, if it does not, it is almost certainly 32-bit.
uname -i

== Enabling Coversheets ==
* Login to the EPrints Archive as an administrator and go to the '''Admin''' page and under the '''System Tools''' tab, click on '''EPrints Bazaar''' button.
* On the EPrints Bazaar page scroll and click on '''Enable''' next to the '''OpenOffice Toolkit''' package.
* If the OpenOffice Toolkit package installs successfully, click on '''Enable''' next the '''Coversheets''' package.
* If the Coversheets package successfully installed. Click on the '''Admin''' link in the top menu bar and under the '''System Tools''' tab click on '''Start OpenOffice'''.
* When the page reloads next click on '''Start Indexer''', if t is not already started.
* Coversheets should now be installed and ready to go. You can test this by following the instructions under '''[[#Deploying Coversheets|Deploying Coversheets]]'''.

== Deploying Coversheets ==
* Logged in as an adminstrator, click on '''Manage records''' then '''Coversheets'''. If you cannot find the the '''Manage records''' link you can go straight to the list of coversheet records at (substituting '''example.eprints.org''' for the hostname of you Eprints repository):
http://example.eprints.org/cgi/users/home?screen=Listing&dataset=coversheet
* Under the Coversheets page, click on '''Create New Coversheet'''. Fill in the '''Name''' and Description fields under '''Apply to''' checked the types you want to use a coversheet for.and set '''Priority''' to '''1'''. If you wish to apply the coversheet to other types make sure they are checked as well.
* Then, under '''Documents''' -> '''Front Page(s)''' upload the template coversheet front page, which you can adapt from the template at the URL below, before clicking '''Update''' button at the button of the page:
http://files.eprints.org/1047/2/frontfile-example.odt
* When the page reloads, click on the '''Exit'' button to go back to the Coversheet index page.
* On the Coversheet index page, click on the icon with a green tick next to the coversheet you just added and then click on the '''Activate''' button on the page that loads.
* Now follow the '''[[#Testing Coversheets|Testing Coversheets]]''' instructions to check that everything is configured and working as expected.

== Testing Coversheets ==
* Now add an EPrint as usually, ensuring it is of one of the types you selected under '''Apply to''' earlier.
* Once you have deposited the EPrint and moved it to the repository. Click on the link to download the PDF. The PDF will load initially without a coversheet.
* Click back to go back to the EPrints web interface and click on the '''Admin''' link.
* On the Admin page click on the '''System Tools''' tab and then click on the '''Status''' button.
* On the Status page click on the link on the '''Background Task Queue'' row. On the page that loads you should be able to see a ''''Document:AddCoversheet''' task pending.
* Once this task disappears from the list, go back to the PDF you loaded previously and do a hard refresh (e.g. '''Ctrl+F5''') of the page.
* If all has gone to plan your PDF document should now have a coversheet.

== Designing your own Coversheet Template ==
* If you have downloaded the example coversheet template from http://files.eprints.org/1047/1/frontfile.odt you can adapt it for your own EPrints repository by editing it in [https://www.openoffice.org/download/index.html OpenOffice] or [https://www.libreoffice.org/download/libreoffice-fresh/ LibreOffice].
** Unfortunately, you cannot edit this in Microsoft Office as the document needs to be saved in .odt format.
* Once you have opened the example coversheet template in OpenOffice or LibreOffice you can change the logos (images) used and the layout of the page as you choose fit.
* Where a word is enclosed with '''##''' either side (e.g. ''##title##''). Then this will be substituted with the appropriate EPrint attribute. By default the following tags can be put into a template coversheet to be replaced by the value for that EPrint attribute:
** ##title##
** ##type## (e.g. article, conference item, book section, etc.)
** ##url## (to the EPrint on your EPrints repository)
** ##date## (of when the EPrint was published)
** ##citation## (of the EPrint as it would appear in an EPrints search result)
** ##creators## (list of authors/editors of the EPrint)
** ##doi_url##
* Once you have finished your design, before saving make you do not have any white space at the end of the document, as this may cause a blank page to be added between your coversheet and main document.
* After saving the file, you can upload to your EPrints repository as described in '''[[#Deploying Coversheets|Deploying Coversheets]]'''.

== Tips and Tricks ==
=== Adding Extra Coversheet Tags ===
Extra coversheet tags can be added by editing '''z_coversheet_tags.pl''' under the archives '''cfg/cfg.d/''' directory.

=== Configuring 'Apply to' Options ===
Additional options (e.g. eprint_status, userid, series, publication, etc.) can be added to the '''$c->{license_application_fields}''' in '''z_coversheet.pl''' under the archives '''cfg/cfg.d/''' directory. This will cause these options to appear in the form for editing a particular coversheet.

== Troubleshooting ==
=== Troubleshooting whilst Designing your own Coversheet Template ===
==== Adding and formatting tags on your Coversheet Template ====
Make sure when you add tags (e.g. ##title##) to your coversheet template you type the whole string in one go. Try to avoid copying and pasting tags about, especially avoid copy parts of tags. Also be careful when changing the formatting (e.g. font size, colour, etc.) of a tag, making sure you change the format for the whole tag.

Not doing these things could lead to the underlying representing of the whole tag being broken up by styling elements, meaning that the coversheet package will no be able to find these tags to substitute them with the appropriate attribute from the EPrint. So when you come to look at the coversheet for your document, you will see the tag rather than the substituted attribute.

===Known issue with Centos 7===
/tmp folder on Centos 7 has unexpected behaviours, causing the generated coversheet to disappear.

A solution is to change the tmp directory location to /opt/eprints3/tmp:

in cfg.d/session.pl, add the following line to line 22:
$ENV{'TMPDIR'} = "/opt/eprints3/tmp";

create the directory:
mkdir /opt/eprints3/tmp

Installing EPrints on RHEL/Fedora/CentOS

2016-01-22T17:06:41Z

Jy2e08@ecs.soton.ac.uk: /* Upgrade from previous 3.3 */

[[Category:Installation]]

==Requirements==

* RedHat Enterprise/CentOS 7 (earlier versions may work)

==Installing==

Add the rpm.eprints.org repository key:

rpm -ivh http://rpm.eprints.org/rpm-eprints-org-key-1-1.noarch.rpm

... the rpm.eprints.org EPrints repository:

rpm -ivh http://rpm.eprints.org/eprints/noarch/rpm-eprints-org-1-1.noarch.rpm

... on '''RHEL 5.x only''' the rpm.eprints.org RHEL updates repository:

rpm -ivh http://rpm.eprints.org/RHEL/5Server/noarch/rpm-eprints-org-RHEL-5-1.noarch.rpm

... on '''RHEL 6.x only''' install antiword if installing EPrints 3.2.x or earlier (from 3.3 onwards only used to as a Word -> PDF converter so not strictly necessary):

rpm -ivh http://rpm.eprints.org/RHEL/5/i386/antiword-0.37-1.i386.rpm
# or for 64 bit:
rpm -ivh http://rpm.eprints.org/RHEL/5/x86_64/antiword-0.37-1.x86_64.rpm

Upgrade your XML libraries:

yum upgrade libxml2 libxslt perl-XML-LibXML perl-XML-LibXSLT

Install EPrints 3:

yum install eprints # 3.3.x and later
yum install eprints3 # 3.2.x

===Other sources for dependencies===

The following RPM repositories may be useful for finding other dependencies required by EPrints that aren't part of the core RHEL system.

http://fedoraproject.org/wiki/EPEL - Fedora Extras for RHEL.

http://pkgs.repoforge.org/rpmforge-release/ - RPMforge, which covers a very large range of Perl modules plus others.

[http://www.imagemagick.org/script/binary-releases.php ImageMagick] provide an RPM for RHEL/CentOS 5. At time of writing the RPM requires fftw3, fltk, jasper and openexr which are available from ''RPMForge''. libwebp is available from [http://rpm.eprints.org/RHEL/5/ rpm.eprints.org].

==SELinux==

If you're using SELinux on your server you will need to give Apache read/write access to the documents directory for all repositories you create and the eprints var folder (indexer log, ticker files):

chcon -R -h -t httpd_sys_script_rw_t /usr/share/eprints/archives/[repoid]/documents/
chcon -R -h -t httpd_sys_script_rw_t /usr/share/eprints/var/

==Getting Started==

[[Getting Started with EPrints 3]]

== Troubleshooting ==

=== Failed to parse XML file ===

When installing EPrints on RHEL6 (may apply to other versions), If you get the error:
Failed to parse XML file:
/usr/share/eprints/lib/lang/en/phrases/system.xml: Entity: line 396: parser error : Entity 'nbsp' not defined age or title page. If there are more...

Run
sed -i 's/'''&'''nbsp;/ /g' /usr/share/eprints/lib/lang/en/phrases/system.xml

then navigate to the root of your EPrints install (/opt/eprints or /usr/share/eprints) and run
bin/generate_views *repository_id*
bin/epadmin reload *repository_id*

=== Upgrade from previous 3.3 ===
After a upgrading from previous 3.3, your existing repository's database may need updating.
bin/epadmin update [arcid]

Installing EPrints on RHEL/Fedora/CentOS

2016-01-22T17:06:08Z

Jy2e08@ecs.soton.ac.uk:

2014-08-05T09:11:05Z

Jy2e08@ecs.soton.ac.uk: /* Mandatory Fields */

[[Category:Management]]
[[Category:Howto]]
See also: [[Files/EThOS_webservice_download_tool]]
<blockquote>''Eprints 3 users - the OAI interface to expose UKETD_DC is already bundled with the Eprints 3 distribution. However, it is still necessary to configure your installation to allow entry of metadata conforming to EThOS requirements. To this end you may find the EPrints v3 Configuration Notes helpful.''
 
[http://ethostoolkit.cranfield.ac.uk/tiki-index.php?page_ref_id=28 Guide to using an existing repository]
</blockquote>

[http://ethostoolkit.cranfield.ac.uk/tiki-index.php?page=EPrints+v3+Configuration+Notes EPrints v3 Configuration Notes]

[http://ethostoolkit.cranfield.ac.uk/tiki-index.php?page_ref_id=47 UKETD_DC: The metadata core set recommended by EThOS]

=Mandatory Fields=

{| border="1" cellpadding="5" cellspacing="0"
!Ethos Field name
!EPrints field used by Ethos plugin
!Comments
|-
|Title
|title
|
|-
|Author
|creators_name
|
|-
|Awarding Institution
|institution
|
|-
|Year of Award
|date
|Implicitly assumed that this is date on title page of thesis.
|-
|Type
|type
|Material type, i.e. Thesis
|-
|Qualification level
|thesis_type
|Default thesis_type values mix qualification level (eg. Masters) and qualification name (eg. PhD). Suggest refining thesis_type values and optionally adding new thesis_name field.
|-
|Qualification name
|thesis_name
|Not in EPrints default. Name of the degree, e.g. Ph.D., M.D.
|}

=Optional Fields=

{| border="1" cellpadding="5" cellspacing="0"
!Ethos Field name
!EPrints field used by Ethos plugin
!Comments
|-
|Alternative Title
|alt_title
|Not in EPrints defaults.
|-
|Supervisor(s)/advisor
|advisor
|Not in EPrints defaults. Plugin expects single value text field. Suggest using default Contributors field instead (adjust plugin to look for contributors with Thesis advisor role).
|-
|Subject keywords
|subjects
|
|-
|Abstract
|abstract
|
|-
|DDC
|
|
|-
|LCC
|
|
|-
|LCSH
|
|
|-
|MESH
|
|
|-
|UDC
|
|
|-
|Author Affiliation
|department
|
|-
|Publisher
|publisher
|Note publisher not in default thesis workflow.
|-
|Sponsors
|sponsors
|Not in EPrints defaults.
|-
|Grant number
|
|
|-
|Qualification name
|thesis_name
|Not in EPrints defaults.
|-
|Language
|language
|Not in EPrints defaults.
|-
|Institution item page URL
|
|Note plugin uses both $eprint->get_url and official_url for dc:isReferencedBy.
|-
|Citations
|citations
|Not in EPrints defaults.
|-
|Included/Quoted work
|referencetext
|
|-
|Rights
|rights
|Not in EPrints defaults.
|-
|Embargo Type
|
|
|-
|Embargo date
|date_embargo
|Not in EPrints defaults. Not to be confused with document.date_embargo.
|-
|Embargo reasons
|embargo_reason
|Not in EPrints defaults. Plugin expects single value text field.
|-
|Identifier
|
|Plugin uses $document->get_url
|}

=Deprecated Fields=

{| border="1" cellpadding="5" cellspacing="0"
!Ethos Field name
!EPrints field used by Ethos plugin
!Comments
|-
|File Format
|document.format
|
|-
|File Size
|
|
|-
|Checksum
|checksum
|Not in EPrints defaults
|-
|File Version
|
|
|}

=Other (not in Ethos spec)=

{| border="1" cellpadding="5" cellspacing="0"
!Ethos Field name
!EPrints field used by Ethos plugin
!Comments
|-
|Editor?/Contributor?
|editors_name
|dc:contributor
|}