Editing SWORD 1.3 (section)

== Writing your own Importer ==

In EPrints 3.2, you need to create two things to enable a new importer

# You need to configure the repository to recognise a new packagge format, and associate that format with the code that handles it
** This lives in <tt>~~eprints/archives/<ID>/cfg/cfg.d/</tt>
# You need to write the actual package that handles the file being deposited
** This live in <tt>~~eprints/archives/<ID>/cfg/plugins/EPrints/plugin/Sword/Import/</tt>
** For complex importers, you may end up writing multiple packages - its Perl.... TMTOWTDI

=== Configuration file ===
This is relatively easy file to write - for example:

<pre>
  # Add in the RJ_Broker acceptance type
  $c->{sword}->{supported_packages}->{"http://opendepot.org/broker/1.0"} = 
  {
    name => "Repository Junction Broker",
    plugin => "Sword::Import::RJ_Broker",
    qvalue => "0.8"
  };
</pre>

* The <tt>name</tt> is the string that's shown in the servicedocument
* The <code>plugin</code> is the package used to handle the file deposited
* The <tt>qvalue</tt> is what's known as the "Quality Value" - how closely the importer matches all the metadata wanted by the repository.
** The theory is that clients have a list of packages they can export as, and servers have a list of packages they understand - therefore a client can determine the best package for that transfer, based on relative QValues.

=== Importer Plugin ===
The importer plugin is a perl package that handles the deposited file, and creates a new record in the repository for the record deposited.

The Importer system is, as with all EPrints code, deeply hierarchical:

# <code>EPrints::Plugin::Sword::Import::MyImporter</code> will inherit most of its code from <code>EPrints::Plugin::Sword::Import</code>
# <code>EPrints::Plugin::Sword::Import</code> is never run directly, and inherits most it its functions from <code>EPrints::Plugin::Import</code>
# <code>EPrints::Plugin::Import</code> is another ''base class'' (one that is there to provide central functions), and inherits from <code>EPrints::Plugin</code>
# <code>EPrints::Plugin</code> is the ''base class'' for all plugins.

In practice, the best way to learn how importers are written is to look at existing importers (<tt>~~eprints/perl-lib/EPrints/Plugin/Sword/Import/...</tt>)

==== Basic framework ====
The very basic framework for an importer is just to register the importer with EPrints, and leave all functions to be handled by inheritence:

<pre>
package EPrints::Plugin::Sword::Import::MyImporter;

use strict;

use EPrints::Plugin::Sword::Import;
our @ISA = qw/ EPrints::Plugin::Sword::Import /;


sub new {
  my ( $class, %params ) = @_;
  my $self = $class->SUPER::new(%params);
  $self->{name} = "My Sword Importer";
  return $self;
} ## end sub new

1;

</pre>

This is actually pretty useless as all it will do is create a blank record, with the deposited file attached as a document. To be useful, it needs to somehow read in some metadata and maybe attach some files.

The first important task will be to handle the file deposited. For this, you need to create a function called <code>input_file</code>, and it will have a framework something like:

<pre>
##        $opts{file} = $file;
##        $opts{mime_type} = $headers->{content_type};
##        $opts{dataset_id} = $target_collection;
##        $opts{owner_id} = $owner->get_id;
##        $opts{depositor_id} = $depositor->get_id if(defined $depositor);
##        $opts{no_op}   = is this a No-op?
##        $opts{verbose} = is this verbosed?
sub input_file
{
    my ( $plugin, %opts) = @_;

    my $session = $plugin->{session};

    # needs to read the xml from the file:
    open my $fh, $file;
    my @xml = <$fh>;
    close $fh;
    my $xml = join '', @xml;

    my $epdata = {};
    my $epdata = $plugin->parse_xml($xml);
    my $eprint = $dataset->create_object( $plugin->{session}, $epdata );
    return $eprint;
}

sub parse_xml
{
    my ($plugin, $xml) = @_;
    my $epdata = {};

    #### do stuff

    return $epdata;
}
</pre>