=pod

Generally speaking when upgrading EPrints v2 you should unpack and install eprints to the same path as your current version. The installer will detect the existing version and upgrade it. Existing files which have been altered by you should be automatically backed up so they don't get lost. But if your hacks are important then you should probably back them up by hand before upgrading.


Always stop apache before upgrading.

Always make sure your system is fully backed up before upgrading.

Then you should follow the specific instructions for each stage from your old version to your new version...

=head1 Updating from EPrints 1

A tool for assisting with this is available from http://software.eprints.org/files/

=head1 Updating from EPrints2-alpha-2 to EPrints 2.0

Too much of the configuration of the archive has changed to document individually. See
the C<CHANGELOG> file if you're really interested. If you have more than one
archive, then do each step for each one. Our example is the archive with the ID I<foobar>.

To upgrade we suggest you use the UNIX C<diff> command to make a records of changes 
you made to the archive config directory.

 % diff /opt/eprints2/defaultcfg/ /opt/eprints2/archives/foobar/cfg/

Store the output from diff somewhere safe.

Remove C</opt/eprints2/archives/foobar/cfg/>

Now install eprints 2.0 and agree to upgrade when it asks.

Copy the new default configuration into your archive dir:

 % cp -R /opt/eprints2/defaultcfg/ /opt/eprints2/archives/foobar/cfg/

Work through the "diff"  you produced, and re-apply the changes 
to the contents of C</opt/eprints2/archives/foobar/cfg/>.

You also need to execute the following SQL command.

 UPDATE document SET security='' WHERE security='public';

To connect to mysql via the command line run:

 % mysql -u eprints foobar -p

And enter the database password for that archive.

Now re-run C<generate_apacheconf> and restart apache.

Upgrading from 2.0 should be less painful than this, the config
files should change less dramatically from now on.



=head1 Updating from EPrints 2.0 to EPrints 2.0.1

This release is mostly a bug fix release. There are a few 
bugs in the config files which you should fix by hand. 

After upgrading EPrints, repeat these steps for the cfg
directory of each archive you have created:

=over 4

=item *

In C<citations-en.xml> in the citation for poster, the year field is incorrecly named &years; rename it to &year; 

=item *

(This is not essential) Also on the citations file for the "eprint" and "user" citation types: add a E<lt>ep:linkhereE<gt> .... E<lt>/ep:linkhereE<gt> just inside the E<lt>ep:citationE<gt> tag.

=item *

There was a bug in C<ArchiveFreeTextIndexingConfig.pm> which meant
that "return" was treated as part of a word, rather than a word break. Unless you have modifed that file, just
replace it with the new one from C</opt/eprints2/defaultcfg/>

=item *

(This is not essential) The title for the abstract block never gets added to the page. Edit C<ArchiveRenderConfig.pm> - search for eprint_fieldname_abstract and add the following line as the next line:

  $page->appendChild( $h2 );

=back


=head1 Updating from EPrints 2.0.1 to EPrints 2.1

These release fixes a few bugs but the main point is adding the subscriptions feature and support for OAI 2.0. See the NEWS file in the distribution for more information.

After upgrading EPrints, repeat these steps for each archive you have created:

=over 4

=item *

Upgrade the SQL tables - EPrints 2.1 needs to make some small changes to the database. Run:

 % bin/upgrade ARCHIVEID

This script will explain the changes it is making. It will require the MySQL root password.

If you want an extra level of protection, you may want to run mysqldump to backup the database.

=item *

If you are not using the OAI system then just copy the new ArchiveOAIConfig.pm configuration file over your old one. The new one can be found in /opt/eprints2/defaultcfg/ArchiveOAIConfig.pm.

If you have already configured the OAI system then you need to add the required configuration for OAI 2.0. These can be copied from /opt/eprints2/defaultcfg/ArchiveOAIConfig.pm. The two relevant sections are the block titled "OAI-PMH 2.0" and the subroutine C<make_metadata_oai_dc_oai2>. Copy these into your archives ArchiveOAIConfig.pm and modify them if needed.

=item *

Look at the section on setting up subscriptions in the "Installation" chapter.

You need to add some more items to the cron tab to mail out the subscriptions. One set of new cron entries per archive.

=item *

The call for EPrints::EPrint->new() has changed the order of the parameters
(to standardise it with Subject, User, etc.).

In ArchiveRenderConfig.pm edit:

        my $target = EPrints::EPrint->new( $session,
                $session->get_archive()->get_dataset( "archive" ),
                $eprint->get_value( "commentary" ) );

to be:

        my $target = EPrints::EPrint->new( $session,
                $eprint->get_value( "commentary" ),
                $session->get_archive()->get_dataset( "archive" ) ) ;

(swapping the order of the last 2 parameters)

=back

=head1 Updating from EPrints 2.1 (or 2.1.1) to EPrints 2.2

Upgrade eprints software to the new version then (for each archive)

=over 4

=item *

Upgrade the SQL tables - EPrints 2.2 needs to make some small changes to the database. Run:

 % bin/upgrade ARCHIVEID


=item cfg/ArchiveOAIConfig.pm

In the sub eprint_to_unqualified_dc change this line:

  push @dcdata, [ "creator", EPrints::Utils::tree_to_utf8( 
      EPrints::Utils::render_name( $session, $author, 0 ) ) ];

to this:

  push @dcdata, [ "creator", EPrints::Utils::make_name_string( $author ) ];

=item cfg/ArchiveRenderConfig.pm (optional)

You may wish to add the following to "eprint_render", after the commentary section. It will add 'type' to the abstracts page (although not unless you run generate_abstracts
  
 	$table->appendChild( _render_row(
 		$session,
 		$session->html_phrase( "eprint_fieldname_type" ),
 		$eprint->render_value( "type"  ) ) );

=item cfg/ArchiveConfig.pm (optional)

In the 2.1 default configuration a user could not view their own secure documents if they were not an editor. This was silly. Fix it in sub can_user_view_document:

Change the block:

	if( $security eq "staffonly" )
        {
                # If you want to finer tune this, you could create
                # a new priv. and use that.
                return $user->has_priv( "editor" );
        }

to:

	if( $security eq "staffonly" )
        {
                # If you want to finer tune this, you could create
                # new privs and use them.

                # people with priv editor can read this document...
                if( $user->has_priv( "editor" ) )
                {
                        return 1;
                }

                # ...as can the user who deposited it...
                if( $user->get_value( "userid" ) == 
			$eprint->get_value( "userid" ) )
                {
                        return 1;
                }

                # ...but nobody else can
                return 0;

        }



=item cfg/ArchiveRenderConfig.pm (optional)

You may wish to add subscriptions to the user_render_full method so staff can see what subscriptions a user has. Just before 

  	$info->appendChild( $table );

Add:
 
 	my @subs = $user->get_subscriptions;
 	my $subs_ds = $session->get_archive->get_dataset( "subscription" );
 	foreach my $subscr ( @subs )
 	{
 		my $rowright = $session->make_doc_fragment;
 		foreach( "frequency","spec","mailempty" )
 		{
 			my $strong;
 			$strong = $session->make_element( "strong" );
 			$strong->appendChild( $session->make_text( 
				$subs_ds->get_field( $_ )->display_name( $session ) ) );
 			$strong->appendChild( $session->make_text( ": " ) );
 			$rowright->appendChild( $strong );
 			$rowright->appendChild( $subscr->render_value( $_ ) );
 			$rowright->appendChild( $session->make_element( "br" ) );
 		}
 		$table->appendChild( _render_row(
 			$session,
 			$session->html_phrase(
 				"page:subscription" ),
 			$rowright ) );
 				
 	}

=item Subject Editors (optional)

If you want to add the feature which allows the editor to set a search which limits the scope of what an editor may edit (eg. only books, or only things under oceanography in the subject table) you must add in metadata-types.xml ...

To the end of E<lt>type name="editor"E<gt>

    <field name="editperms" staffonly="yes" />
    <field name="frequency" required="yes" />
    <field name="mailempty" required="yes" />

And to the end of E<lt>type name="admin"E<gt>

    <field name="editperms" />
    <field name="frequency" required="yes" />
    <field name="mailempty" required="yes" />

And then to ArchiveConfig.pm add (near "subscription fields" )

 # Fields used for limiting the scope of editors
 $c->{editor_limit_fields} =
 [
         "subjects",
         "type"
 ];

=item Translated Phrase Files (non-english archives only)

There is a tool in http://software.eprints.org/files/contrib/update_phrases/ which will assist with identifying changes made in the English version which should be applied to your translated version(s).

=item Rehash Documents (optional but recommended)

If you want to use the "probity" feature (see elsewhere in documentation for more information) you should run the rehash_documents command to generate a hash of each document file in the system.

=item Updating the website (optional)

You may also wish to update the website to reflect that eprints 2.2 is OAI 2.0 compliant. Also re-running generate_static will update the version number for eprints where mentioned.

=item 100 matches per page (optional)

10 matches per search page was a little low. You may wish to up it to 100, which seems to work better for people.

=item GDOME support

If you wish to enable GDOME support (faster, better XML library) install the additional required libraries then edit the flag in SystemSettings.

The additional 2 changes are required for GDOME support.

In ArchiveConfig.pm in sub get_entities change

        $entities{ruler} = $archive->get_ruler()->toString;
to 
        $entities{ruler} = EPrints::XML::to_string( $archive->get_ruler() );

and in ruler.xml change the XML header to:

 <?xml version="1.0" ?>
 <!DOCTYPE ruler >

=item Home grown plugins and scripts (API changes)

If you've made your own scripts using the eprints modules then you should be aware of some changes to those modules:

=over 4

=item $metafield->get_dataset() 

MetaFields no longer known what dataset they belong to

=item $metafield->set_dataset()

MetaFields no longer known what dataset they belong to

=item $metafield->get_values( $session )

Now use: $metafield->get_values( $session, $dataset )

=item XML functions

All the XML handling now uses EPrints::XML as an abstraction to the differences between XML::GDOME and XML::DOM. 

Please use EPrints::XML::to_string( $node ) rather than $node->toString as in GDOME toString does not work as expected on DocumentFragments.

=item EPrints::Config::parse_xml()

Removed. Use EPrints::XML methods instead.

=item $db->get_values( $field ) 
     
Now use: $db->get_values( $field, $dataset )

=item XHTML Page generation functions changed 

Should not cause any problems, but might.

=item $searchfield->set_value()

Removed.

=back


=back

=head1 Updating from EPrints 2.2 (or 2.2.1) to EPrints 2.3

This version adds some more functionality and uses apache in a slightly different way. The full text indexing tool adds some more requirements.

=head2 Recompile Apache

EPrints 2.3 requires an additional mod_perl hook, TRANS. I suggest you compile apache with "EVERYTHING=1" instead of "AUTHEN=1 AUTHZ=1" (see the required software section of the 2.3 manual). mod_rewrite is not used any more.

=head2 libapreq

Version 2.3.7+ of EPrints do not require this module. It was a pain to install. 2.3.0 to 2.3.6 do require it, but we recommend you run 2.3.7 or later.

=head2 Install tools used by full-text indexer

See the chapter "Required Software", section "Full Text Indexing". Follow the instructions.

=head2 Upgrade eprints software to version 2.3


As usual download and extract the latest (stable) version and run ./configure

Stop the webserver

Run ./install.pl as usual

For each archive run 

 % bin/upgrade ARCHIVEID

Update the apache config:

 % bin/generate_apacheconf

Start the webserver

=head2 Add the new icons & update the style sheets

The new input interface has up and down buttons to let you rearrange the values in lists, such as authors. If you don't copy them into your live archives you'll probably see ugly text of "UP" and "DOWN". You need to put them in your archives "images" dir then use generate_static to copy them to the live website.

 % cp defaultcfg/static/general/images/multi_*.png archives/ARCHIVEID/cfg/static/general/images

Copy in the new VLit stylesheet. 

 % cp defaultcfg/static/general/vlit.css archives/ARCHIVEID/cfg/static/general

Copy any new styles you want from 

 defaultcfg/static/general/eprints.css 

to

 archives/ARCHIVEID/cfg/static/eprints.css 

I suggest everything after the line which starts ".subject_browser_opts, .subject_browser_selections, .subject_browser_search". This isn't essential, but will make your site look nicer.

Now run:

 % bin/generate_static ARCHIVEID

=head2 Start the indexer

EPrints 2.3 does not create the search index in the same way as 2.2 did. It has a background daemon which builds new indexes and then copys them over the old indexes when they are ready. This can potentially take quite a long time, but means that editing records will be much faster (no need to keep reindexing).

If you have some buggy or experimental archives which you do not wish the indexer to process add 
E<lt>indexE<gt>noE<lt>/indexE<gt> to the main XML config file for that archive.

Only one copy of the indexer runs, no matter how many archives you have. To start it run:

 % bin/indexer start

You should make the indexer automatically start and stop if the machine is rebooted. See the main documentation about the indexing system.

=head1 Updating from any of EPrints 2.3.0 through EPrints.2.3.6 to EPrints 2.3.7

Both the below changes are optional, although recommended.

=head2 Short URLs

You may wish to enable the short urls feature; just add 
 $c->{use_short_urls} = 1;
to ArchiveConfig.pm

=head2 XSLT for OAI

2.3.7 introduced an XSLT stylesheet for OAI requests. If you install it and
view your OAI requests in Mozilla or IE it should be rendered in a human
readable form.

 % cp defaultcfg/static/general/oai2.xslt archives/ARCHIVEID/cfg/static/general

