Editing Migration (section)

== Migration Toolkit ==

The migration toolkit, available from http://files.eprints.org/ does quite a bit of the heavy lifting. It is intended to help configure an EP3 archive to have the same files, eprint types etc. as an EPrint 2 repository and then copy the data over.

Release 1.0-beta-1 should be a big improvement over 0.2 but it still doesn't do everything. 

=== Installation ===

==== Backup ====

First of all make sure your EPrints 2 repository is backed up, just in case things don't go to plan. You already back it up daily anyway, right...?

==== Mtoolkit ====

Un-tar the package on the same machine as your EPrints 2 repository.

If your EPrints 2 was not installed in /opt/eprints2 then you'll need to modify the first line of the two .pl scripts in the toolkit.

==== EPrints 3 ====

Minimum version required: 3.0.2 (This version introduces some very small options and bugfixes aimed at migration).

Also, get an EPrints 3 server set up. This can be either on the same machine (you'll need a separate instance of apache as ep2 and ep3 can't run under the same server at the same time, put it on port 8080 for now - see http://httpd.apache.org/docs/2.0/install.html for instructions - put it in another directory using the --PREFIX option!), or on a different machine. Get a repository created (probably with the same ID as your ep2 repo, although that's not essential). The database will need to be a different name or you'll get in an utter mess.

=== mkconfig.pl ===

This tool takes the id of an EPrints 2 repository and generates a number of EPrints 3 config. files. Copy these files into the cfg dir of your EPrints 3 repository. It also creates a file called migration_notes.txt with some helpful comments of anything it's messed with.

Get your (empty) EP3 repository up and running using these configuration files. 

=== export3data.pl ===

This script exports the data from your EPrints 2 repostory in a format which can be imported by EPrints 3.

There have been some problems with exporting non Latin characters (e.g. letters with accents).  If you have any problems, these can probably be solved by editing the export3data script and adding the following line (put it just under the first line).

  use encoding 'utf8';

To export the data do the following:

  export3data.pl ARCHIVEID eprints > eprints.xml
  export3data.pl ARCHIVEID users > users.xml
  export3data.pl ARCHIVEID subjects > subjects.xml

eprints.xml references the full paths of the files in EPrints 2. If your EPrints 3 is on a different machine you'll need to either make sure they are the same on the new machine or do a big search-and-replace on eprints.xml!

If the script has any problems, run with the 'skiplog' argument:

  export3data.pl --skiplog errors.txt ARCHIVEID eprints > eprints.xml

Any items with problems will be ignored, but the ids of them will be recorded in the 'errors.txt' file.  Export these by hand if they are important.

=== Importing ===

EPrints 3.0.2 no longer needs the hacks which were required for mtoolkit 0.2

=== Empty out any test data ===

To erase the current data in your EP3 repository use:

 bin/epadmin erase_data ARCHIVEID

=== Import the data ===

To import the subjects and users do:
 /opt/eprints3/bin/import_subjects --verbose --force --xml ARCHIVEID subjects.xml
 /opt/eprints3/bin/import --verbose --migration ARCHIVEID user XML users.xml
If something goes wrong with subjects or users, use epadmin erase_data to empty the database and start again.

To import the EPrints do:
 /opt/eprints3/bin/import --verbose --migration ARCHIVEID eprint XML eprints.xml
If something goes wrong with importing the eprints, use epadmin erase_eprints, to just erase the eprints data so you don't need to redo subjects and users.

the --migration option tells the importer to:
* skip are-you-sure? messages.
* use the eprintid and userid from the XML rather than assigning them.
* use the "datestamp" from the XML rather than assign it.
* load files from the local file system (normally this would be a security hole)

You may encounter some issues with badly formed XML. This is due to non correctly encoded data creeping into your database. It should all be utf-8 but earlier versions of EPrints didn't always check... If your EPrints 2 server is running perl 5.8 you can install the Perl module Encode which will clean up your data, but on our system our EPrints 2 was running on a machine with an older version of Perl and we didn't want to risk upgrading.