
<h1 id='eprints-installation'>Installing the ACIS'
extensions to EPrints</h1>


<toc/>


## Automatic installation

The primary way to install these extensions onto an EPrints
service is to use the <f>install.pl</f> script in the
<f>EPrints</f> 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.


<h3 id='copy-files'>1. Copy perl code and other files</h3>

**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.



<h3 id='page-template-pidaid'>2. Modify page template to
include pidaid.js and pidaid.css</h3>

**For <a href='eprints.html#level3'>person identification aid (level 3)</a>.**

Open your archive's <f>cfg/template-en.xml</f> 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.



<h3 id='id-field-enabled'>3. Make sure id field for authors and
editors is enabled</h3>

**For <a href='eprints.html#level2'>level 2: person id metadata field</a>
and <a href='eprints.html#level3'>level 3: person identification aid</a>.**

Open your archive's
<f>cfg/ArchiveMetadataFieldsConfig.pm</f> 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 <code>hasid</code> 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 <code>hasid</code> parameter should have value
  1.



<h3 id='id-field-label'>4. Set appropriate label for the id
field</h3>

**For <a href='eprints.html#level2'>level 2: person id metadata field</a>
and <a href='eprints.html#level3'>level 3: person identification aid</a>.**


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 <f>phrases-en.xml</f> file in your
archive's configuration directory.  Find and modify the
&lt;ep:phrase&gt; items identified
<code>eprint\_fieldname\_creators\_id</code> and
<code>eprint\_fieldname\_editors\_id</code>.  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.





<h3 id='enable-amf'>5. Patch EPrints::EPrint: enable AMF export</h3>

**For <a href='eprints.html#level1'>exporting eprints metadata</a> (level
1) and to <a href='eprints.html#level4'>notify an ACIS service</a> about
new/modified document data in your EPrints (level 4).**

Open file <f>perl_lib/EPrints/EPrint.pm</f> in your EPrints
installation directory.  Find subroutine
<co>\_move\_from\_archive()</co> and add this after the
initial "my( $self ) = @\_;":

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

Then find subroutine <co>generate\_static()</co> 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.




<h3 id='arc-cfg-amf'>6. Archive configuration: AMF export</h3>

**For <a href='eprints.html#level1'>exporting eprints metadata</a> (level
1) and to <a href='eprints.html#level4'>notify an ACIS service</a> about
new/modified document data in your EPrints (level 4).**


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

<dl>

<dt><C>eprint_metadata_export_AMF_dir</C></dt>

<dd>Pathname of the directory in which to create the AMF files.</dd>

<dt><C>eprint_metadata_export_AMF_idprefix</C></dt>

<dd>A string; will be used as a prefix for AMF text
identifiers.  Default value: empty string.</dd>

</dl>

Example: 

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




<h3 id='arc-cfg-pidaid'>7. Archive configuration: ACIS::PIDAID</h3>

**To <a href='eprints.html#level3'>suggest personal names and
identifiers from an ACIS personal database to your EPrints
users</a>, 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
<f>cfg/ArchiveConfig.pm</f> 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.





<h3 id='arc-cfg-metaupd'>8. Archive configuration: ACIS metadata
update</h3>

**To automatically <a href='eprints.html#level4'>notify an ACIS service</a>
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 <f>cfg/ArchiveConfig.pm</f> in a text editor, and add
<co>eprints\_metadata\_export\_AMF\_metaupdate</co> 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,
     };


<a ref='metaupdate-request-conf'>Explanataion of the first 3
parameters</a> in a different document.  <a
ref='object-dir-levels'>Explanation of the last one</a>
parameter.


Save the file.


<h3 id='install-lwp'>9. Install libwww-perl library</h3>

**To automatically <a href='eprints.html#level4'>notify an ACIS service</a>
about new/modified data in your EPrints (level 4).**


Get the distribution from CPAN: <a
href='http://search.cpan.org/dist/libwww-perl/'>libwww-perl</a>
and install on your system.  Follow installation
instructions in the package.



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

