Installing the ACIS’ extensions to EPrints / ACIS documentation

# Installing the ACIS’ extensions to EPrints

### Table of contents

## Automatic installation

The primary way to install these extensions onto an EPrints service is to use the `install.pl` script in the `EPrints` directory of ACIS. Give the path to your EPrints archive directory as a parameter to that script and follow the instructions. For example:

    $ cd ACIS-1.2.3-20051010d/EPrints
    $ perl install.pl /opt/eprints2/archive/Archive

## Manual installation

In case the automatic installation script fails at some step of the process, you may have to do part of it by yourself.

### 1. Copy perl code and other files

For all the levels.

This includes copying sql_helper, EPrints/{perl_lib,cgi}, AMF-perl, EPrints/{pidaid.*,images} to appropriate directories of your EPrints.

It is unlikely that any problem appears during automatic installation at this step. What may happen is that the release does not contain AMF-perl package, and, therefore, it cannot be installed.

### 2. Modify page template to include pidaid.js and pidaid.css

For person identification aid (level 3).

Open your archive’s `cfg/template-en.xml` file in a text editor. Add references to pidaid.js and to pidaid.css into the template.

It may now look like this:

    ...
    <html xmlns="http://www.w3.org/1999/xhtml"
          xmlns:ep="http://eprints.org/ep2/template">
      <head>
        <title>&archivename; - <ep:pin ref="title" textonly="yes" /></title>
        <style style="text/css" media="screen">
    @import  url(&base_url;/eprints.css);
    @import  url(&base_url;/pidaid.css);     /* PIDAID */
        </style>
        <style style="text/css" media="print">
    @import  url(&base_url;/eprints.css);
    @import  url(&base_url;/pidaid.css);     /* PIDAID */
    @import  url(&base_url;/print.css);
        </style>
        <!-- and PIDAID JavaScript: -->
        <script type='text/javascript' src='&base_url;/pidaid.js' />
        <link rel="Top" href="&frontpage;" />
        ...

Save the file.

### 3. Make sure id field for authors and editors is enabled

For level 2: person id metadata field and level 3: person identification aid.

Open your archive’s `cfg/ArchiveMetadataFieldsConfig.pm` file.

1. find the line which says

       $fields->{eprint} = [

2. near below it find the line, which starts with

           { name => "creators", type => "name",

   and make sure `hasid` parameter in this block is set to 1. The block will look like this:

           { name => "creators", type => "name", multiple => 1, input_boxes => 4,
                   hasid => 1, input_id_cols=>20,
                   family_first=>1, hide_honourific=>1, hide_lineage=>1 },

3. Do the same for the “editors” field. Here the block starts with

           { name => "editors", type => "name"

   Again, the `hasid` parameter should have value 1.

### 4. Set appropriate label for the id field

For level 2: person id metadata field and level 3: person identification aid.

By default, the personal id field in EPrints has label “Creators email (if known)”. We will use this field for personal identifiers and email addresses alternatively. So we suggest to change this field’s label to “Id or email”.

To do that edit the `phrases-en.xml` file in your archive’s configuration directory. Find and modify the <ep:phrase> items identified `eprint_fieldname_creators_id` and `eprint_fieldname_editors_id`. The first one looks like this:

      <ep:phrase ref="eprint_fieldname_creators_id">Creators email (if known)</ep:phrase>

Replace the text in both phrase elements with “Id or email”. The first of the two will now look like this:

      <ep:phrase ref="eprint_fieldname_creators_id">Id or email</ep:phrase>

Save the file.

### 5. Patch EPrints::EPrint: enable AMF export

For exporting eprints metadata (level 1) and to notify an ACIS service about new/modified document data in your EPrints (level 4).

Open file `perl_lib/EPrints/EPrint.pm` in your EPrints installation directory. Find subroutine `_move_from_archive()` and add this after the initial “my( $self ) = @_;”:

    require ACIS::EPrints::MetadataExport::AMF;
    ACIS::EPrints::MetadataExport::AMF::clear_metadata( $self );

Then find subroutine `generate_static()` and find this line in it:

    my $ds_id = $self->{dataset}->id();

After this line add:

    require ACIS::EPrints::MetadataExport::AMF;
    if ( $ds_id eq 'archive' ) {
       ACIS::EPrints::MetadataExport::AMF::export_metadata( $self );
    }

Save the file.

### 6. Archive configuration: AMF export

For exporting eprints metadata (level 1) and to notify an ACIS service about new/modified document data in your EPrints (level 4).

Add these two configuration parameters to the archive configuration in the `get_conf()` subroutine of your `cfg/ArchiveConfig.pm`:

`eprint_metadata_export_AMF_dir`
  Pathname of the directory in which to create the AMF files.
`eprint_metadata_export_AMF_idprefix`
  A string; will be used as a prefix for AMF text identifiers. Default value: empty string.

Example:

    $c->{eprint_metadata_export_AMF_dir} = "/opt/eprints2/archives/Musasi/amf";
    $c->{eprint_metadata_export_AMF_idprefix} = "Musasi:";

### 7. Archive configuration: ACIS::PIDAID

To suggest personal names and identifiers from an ACIS personal database to your EPrints users, while they submit works (level 3).

Obtain database access parameters from administrator of the ACIS service, which you want to use as the source of personal data.

Open your archive configuration file `cfg/ArchiveConfig.pm` in a text editor and add $ACIS::PIDAID::CONF variable to the get_conf() subroutine, and put the access parameters into it in this form:

    $ACIS::PIDAID::CONF = {
      host => 'acis.super.edu', # hostname of the ACIS machine
      port => '9099',           # MySQL port on the ACIS machine
      db   => 'ACIS',           # name of the database in MySQL
      user => 'peter',          # username in MySQL terms
      pass => 'jolly',          # password
    #  max_results => '25',     # max number of results to show, optional (def. 15)
    };

Save the changes.

### 8. Archive configuration: ACIS metadata update

To automatically notify an ACIS service about new/modified data in your EPrints (level 4).

To configure ACIS metadata update you must already have a data-exchange agreement with an ACIS service. An arrangement must exists to regularly transfer the AMF metadata files from your EPrints to that ACIS. Then you need to get permission and an archive name to use for the metadata update requests; ACIS administrator will need to know your archive’s host machine IP address.

Open `cfg/ArchiveConfig.pm` in a text editor, and add `eprints_metadata_export_AMF_metaupdate` parameter to the get_conf() subroutine. Its value must be a hash, and it may look like this:

     $c->{eprint_metadata_export_AMF_metaupdate} = {

          # Full URL to send requests to (ACIS)
          'request-target-url' => 'http://acis.super.org/meta/update',

          # Your archive's id for ACIS
          'archive-id'         => 'michigan',

          'log-filename'       =>
                       '/opt/eprints/archives/History/super-org-metaupdate.log',

          # The directory level of the data files, as it is
      # seen by the ACIS service
          'object-dir-levels'  => 1,
     };

Explanataion of the first 3 parameters in a different document. Explanation of the last one parameter.

Save the file.

### 9. Install libwww-perl library

To automatically notify an ACIS service about new/modified data in your EPrints (level 4).

Get the distribution from CPAN: libwww-perl and install on your system. Follow installation instructions in the package.

$Id: eprints-install.text,v 2.1 2005/12/30 20:55:37 ivan Exp $