[[Category:Browse Views]]
[[Category:Documentation Needed]]
== Views ==
Conceptually a ''view'' is a browsable list of eprints split into ''menus'' and a ''list''.

<div align="center">
{| cellpadding="0" cellspacing="0" border="0"
|-
| style="border-color:black; border-style:solid; border-width:1px 1px 0 1px; margin:0; padding:0; text-align:center; font-size:10px" |Menu1
|  
|  
|  
|  
|-
| style="border-color:black; border-style:solid; border-width:0 1px; text-align: left; margin:0; padding:0; font-size:10px"|   Item1_1 ------
| style="font-size:10px"|--->
| style="border-color:black; border-style:solid; border-width:1px 1px 0 1px; margin:0; padding:0; text-align:center; font-size:10px"|Menu2
|  
|  
|-
|style="border-color:black; border-style:solid; border-width:0 1px; text-align: left; font-size:10px"|   Item1_2
|  
|style="border-color:black; border-style:solid; border-width:0 1px; text-align: left; margin:0; padding:0; font-size:10px"|   Item2_1 -----
|style="font-size:10px"|--->
|style="border-color:black; border-style:solid; border-width:1px 1px 0 1px; margin:0; padding:0; text-align:center; font-size:10px"|     LIST    
|-
|style="border-color:black; border-style:solid; border-width:0 1px 1px 1px; margin:0; padding:0; text-align:left; font-size:10px"|   ....
|  
|style="border-color:black; border-style:solid; border-width:0 1px; text-align: left; margin:0; padding:0; font-size:10px"|   Item2_2
| 
|style="border-color:black; border-style:solid; border-width:0 1px 1px 1px; margin:0; padding:0; text-align:left; font-size:10px"|   ....
|-
|  
|  
|style="border-color:black; border-style:solid; border-width:0 1px 1px 1px; margin:0; padding:0; text-align:left; font-size:10px"|   ....
|  
| 
|}
</div>
In a ''menu'' values of one (or more) fields are listed, and a link points to the collection of all items with that particular value in that field.

The ''list'' contains the final list of eprints with field values as determined by the menus above it.

== Options available for the views config ==
This link is an [http://wiki.eprints.org/w/Adding_new_views 'How to' about views] with examples.

The general form of views definition is

$c->{browse_views} = [
{ <first view definition> },
{ <second view definition> },
...
{ <last view definition> },
];

(be careful about commas and semicolons). The order of the view definitions determines the order in which these will appear in the <nowiki>http://repoid/view/</nowiki> page.

Each view definition is a collection of attributes, given as

attribute1 => value1,
attribute2 => value2,
...

(again, the ''value'' should end by a comma). The ''value'' can be
*''integer''
*''string'' enclosed by quotation marks (") or by apostrophes (')
*''array'' which starts by a square bracket [ followed by the elements of the array (separated by commas) and closed by ] or
*''hash'' which is a list of "attribute => value" pairs enclosed by curly brackets { and }.
Thus the browse_views definition is an array of hashes.

Attributes marked by (V) are ''view'' attributes and are in the view definition; attributes marked by (M) are ''menu'' attributes and should be used only in [[#Menu options|menu definitions]].

==Basic options==

Options in the first category are ''view'' options.

{| border="1" cellpadding="4" cellspacing="0"
|- valign="top"
| id (V)
| (mandatory) String, this is the ID by which you will refer to this view, and also the name of the top directory in <nowiki>http://repoid/view/</nowiki>. This is the value of the ''browse_link'' attribute in [[eprint_fields.pl]]. Example:

id => 'divisions',
|- valign="top"
|fields (V)
|(deprecated) This attribute describes the field(s) by which the view is built. It has been replaced by the more general [[#Menu options|menus]] attribute.
|- valign="top"
|hideempty (V)
allow_null (V)
new_column_at (V)
render_menu (V)
|These define the default values of the same attributes in all [[#Menu options|menus]]. I.e, if not defined otherwise there, they take this as the default value in this view. "Hideempty" is also used when rendering the [[#View list options|view]] list.
|- valign="top"
|menus (V)
|An array of ''[[#Menu options|menu descriptions]]''. Each ''menu'' is a refinement of the previous ones, and last menu points to the [[#View list options|view list(s)]]. In each menu, as minimum, you should give the field(s) which are used to define entries at that level. The menus definition looks like
menus => [
{ <first menu definition> },
{ <second level menu> },
{ <last level> },
],
You must have at least one menu level.
|- valign="top"
|template (V)
|Define an alternate template for all pages in this view. The template page should be a proper xml file in the <tt>repoid/cfg/lang/<langid>/templates/</tt> directory. The best way is to copy the default.xml file and edit it according to taste.
template => 'view_template',
|- valign="top"
|nolink (V)
|When this is set to 1 by adding
nolink => 1,
then this view won't appear in the outmost <nowiki>http://repoid/view/</nowiki> browse page.
|- valign="top"
| max_menu_age (V)
| Defaults to 86400 (one day in seconds). If the menus in this view has been generated more than that many seconds ago, it is regenerated.
|}

===View list options===
These are the options which determine how the last list page in the menu chain should look like. They must be entered at the outmost ''view'' level.
{| border="1" cellpadding="4" cellspacing="0"
|- valign="top"
|order (V)
|This defines how the items in the view list (at the lowest level) are ordered. The format is 'foo/-bar'. This means that the list will be sorted by 'foo' and then any equal 'foo' values will be reverse sorted by 'bar'. More than 2 fields can be specified. Example:
order => "-date/title",
|- valign="top"
|hideup (V)
|Don't show the "up one level" link in the list page. You ''must'' set this attribute for each menu separately, it is not inherited.
|- valign="top"
|hideempty (V)
|Do not list the empty (undefined) entry in the list. This property inherits to the menus.
|- valign="top"
|nocount (V)
|If set, the "Number of items" line at the top of the page is omitted.
|- valign="top"
|notimestamp (V)
|If set, the "This list was generated on" line at the bottom of the list is omitted.
|- valign="top"
|variations (V)
|An array of strings describing different rendering of the items at the ''list''. For datails see [[#Variations|variations]]. Example:
variation => [ "creators_name;first_letter",
"type", "DEFAULT", ],
|- valign="top"
|layout (V)
|Possible values are
*paragraph (default)
*orderedlist
*unorderedlist
Determines how items in the list (or sublist) is rendered. In the first case each item is a paragraph by itself. In the other cases items are rendered as an ordered (unordered) list.
|- valign="top"
|citation (V)
|The citation style defined in archives/<REPOID>/cfg/citations/eprint/ which is used to render each item. Example:
citation => 'screen',
|- valign="top"
|max_list_age (V)
|Defaults to 86400 (one day in seconds). If the lists in this view were generated more than than many seconds ago, it is regenerated.
|}

===Variations===

Variations, if defined, determine how the final list is rendered. ''Variations'' is an array of strings, for example,

[ "creators_name;first_letter",
"type",
"DEFAULT",
]

For each string in the list, a different rendering is produced, and you can switch from one to the other. The variation "DEFAULT" is the default one, it is always a good practice to include it in the list. If no variation is given, "DEFAULT" is used.

A ''variation definition'' consists of a field name, followed by zero, one or more ''options'' after a semicolon. Options are separated by commas. An ''option'' is either a single attribute, or an attribute, an equal sign, and the value of the attribute. For example,
"creators_name;truncate=4,hideup"
sets the attribute value "truncate" to 4, and "hideup" to 1 (or true).

The following options are available. These options are ''part of the string'' defining the variation, and ''should not be entered'' as attributes.

{| border="1" cellpadding="4" cellspacing="0"
|- valign="top"
|reverse
|Reverses the order in which the groupings are shown. Default is the ordervalue for that field (usually alphanumeric). Useful for dates as you may want the highest values first.
|- valign="top"
|filename
|Changes the filename of the view variation. The default is the name of the metadata field used, so if two variations use the same metadata field with different options, this is needed.
filename=different_filename
|- valign="top"
|first_value
|If a field is multiple, only use the first value. Otherwise each item will appear once for each value.
|- valign="top"
|first_initial
|If using a name, truncate the given name to the first initial. This will make items like "Les Carr" and "Leslie Carr" appear together. Note it will also make "John Smith" and "Jake Smith" appear together too, showing that you really never can win.
|- valign="top"
|first_letter
|The same as 'truncate=1'
|- valign="top"
|truncate
|Use the first X characters of a value to group by. truncate=4 may be useful for dates as it will group by the first four digits (the year) only.
truncate=4
|- valign="top"
|tags
|Useful for fields like keywords where values may be separated by commas or semi-colons. The value is split on these two characters ( , and ; ) and a heading is created for each.
|- valign="top"
|cloud
|Creates a tag cloud. Sets jump to 'plain', cloudmax to 200, cloudmin to 80 and no_separator, then resizes the jump-to links according to frequency of use.
|- valign="top"
|cloudmax
|The % size of the largest tag in a tag cloud.
|- valign="top"
|cloudmin
|The % size of the smallest tag in a tag cloud.
|- valign="top"
|jump
|Possible values are 'plain', 'default', and 'none'. Example:
jump=plain
When set to 'plain' turns off the 'jump to' text before the list of subheading navigation links. When 'none', then the 'jump' part is not rendered.
|- valign="top"
|no_seperator (sic)
|Turns of the separator between each subheading navigation link (by default a vertical bar symbol).
|- valign="top"
|string
|Uses values 'as is'. No ordervalues, no phrases.
|- valign="top"
|hideup (since 3.1.1)
|Defaults to "0". If set to "1" this hides the "up to parent" link (often you want to hide this on .include files)
|- valign="top"
|render_fn
|Name of a function to render this groupings list of items. For an example, see views_render_items_example.pl
|}

===Menu options===

These options can only be used in the '''menu definitions'''.

{|border="1" cellpadding="4" cellspacing="0"
|- valign="top"
|fields (M)
|Obligatory, an array of field identifiers. Items in all fields are merged together. For example, to define a list of those those who are either authors or editors or both, use the definition

fields => [ "creators_id", "editors_id" ],

Even if there is a single field, you must use square brackets, such as

fields => [ "subjects" ],

<div style="color: #662211; background-color:#ddffdc; border:1px solid black; padding:3px;">'''Important!''' All fields must have the same type - i.e. you cannot mix titles and authors, say.</div>

You can also add extra rendering info to the field name, without the "render_" prefix. For example, to make a date have resolution year, you would write

fields => [ "date;res=year" ],

or, ordering authors by their ''given'' names rather than by their family names:

fields => [ "creators_name;order=gf" ],

You can add ";quiet" to the field name to force non-existing values to appear as empty space rather than the ugly "UNDEFINED" (see the allow_null property below). You can find the available rendering properties of different fields in the [[Metadata]] section.
|- valign="top"
|allow_null (M)
|The ''undefined'' value among the possible values of the fields does not show up in the generated view. To allow the undefined value to appear as well, set

allow_null => 1,

Beware: the title of the undefined entries will be the ugly UNDEFINED. You might consider to use the ";quiet" rendering option for field names.
|- valign="top"
|hideempty (M)
|If a category is empty, don't show it as an entry. Default value: show all entries, even if they contain no entries. Used only in menus, not at the lower level (list).
Example:

hideempty => 1,
|- valign="top"
|reverse_order (M)
|If set, then the ordering of items in this menu is reversed. Example:

reverse_order => 1,
|- valign="top"
|mode (M)
|Possible values: ''[[#Sections|sections]]'' and ''default'' (default). When defined as ''sections'' then grouping can be defined by the following data:
* ''grouping_function'' (group by first character if not defined)
* ''group_sorting_function'' (how to sort members of a group)
* ''group_range_function''
* ''open_first_section'' the front page should show the first section
See [[#Sections|below]].
|- valign="top"
|hideup (M)
|When set to 1, don't show the "move one level up" link at the top of the page.
|- valign="top"
|render_menu (M)
|The configuration parameter which renders this menu. This should be a string, and also you should define a routine with the same name. For example if you write
render_menu => 'render_view_menu_3col_boxes',
then this menu will be rendered by the routine which is defined in [[views_render_menu_example.pl]] as
$c->{render_view_menu_3col_boxes} = sub
{
...
}
See there for hints how to tweak your own routine.
|- valign="top"
|new_column_at (M)
|Used in menus (not lists) and in default mode. This is an array of integers representing the number of items in a view list before another column is added. For example:

[ 11 ]

The menu is rendered as a single column data if there are less than 11 entries, then there would be 2 columns.

[ 11, 21 ]

This would have one column if there were ten or less values, two columns if there are twenty or less, and three columns for all other cases.

[ 0, 0 ]

This would always have three columns.

[ 2, 3 ]

This would have one column for a single data, two columns for two, and three columns for three or more data.

Add one to the number of integers in the array and you get the maximum number of columns. The entries are evenly distributed in the columns.
|}

===Sections===

When a menu is using "sections", then items on the menu are grouped together. The exact method is defined by defining values for several options. These options go to the ''menus section'' as well.

{|border="1" cellpadding="4" cellspacing="0"
|-valign="top"
|grouping_function (M)
|This function determines how grouping is done. The following predefined functions can be used:
*"EPrints::Update::Views::group_by_a_to_z"
*"EPrints::Update::Views::group_by_first_character" (default)
*"EPrints::Update::Views::group_by_2_characters"
*"EPrints::Update::Views::group_by_3_characters"
*"EPrints::Update::Views::group_by_4_characters"
*"EPrints::Update::Views::group_by_5_characters"
with the usual meaning. If you use 'group_by_a_to_z', all entries not starting with a letter will be discarded.
|-valign="top"
|group_sorting_function (M)
|A costum function which sorts the group identifiers. The only available function
*"EPrints::Update::Views::default_sort"
sorts alphabetically.
|-valign="top"
|group_range_function (M)
|Splits the groups (as determined by the grouping function) into sections so that a group never splits. Groups are rendered separately, but a section is kept on a single page. Available grouping functions are
*"Eprints::Update::Views::no_ranges" (default)
*"EPrints::Update::Views::cluster_ranges_<range>"
where <range> is one of 10, 20, 30, 40, 50, 60, 70, 80, 90, 100, and 200.
|-valign="top"
|open_first_section (M)
|if set, the first section is included in the front page.
|}

==Phrases==

Views can have their own titles and other phrases. If they do not exist, then a default one is used (usually containing the view's id). For examples, see the views.xml file.

{|border="1" cellpadding="3" cellspacing="0"
|-valign="top"
|viewname_eprint_<viewid>
|the name of the browse pages
|-valign="top"
|viewintro_<viewid>
|The phrase to replace the text "Please select a value to browse from the list below." in the top level menu
|-valign="top"
|viewintro_<viewid>/<value>
|Intro phrase on the next level
|-valign="top"
|viewtitle_eprint_<viewid>_menu_<level>
|Title of browse page at level <level>, which is 1, 2, ... In the phrase you can use the pins "value1", "value2", etc. where the number can be one less than the present level; the value of the pin is the actual value of the previous levels. See the example below.
|-valign="top"
|viewgroup_eprint_<viewid>_<filename>
|Used as a pin value for the title on the list pages, when [[#Variations|variations]] are used. <Filename> is the filename defined as the option of the variation, or, if it is not defined, then it is the fieldname at the beginning.
|-valign="top"
|viewtitle_eprint_<viewid>_list
|Title of the list pages of the view. You can use the same pins as before ("value1", "value2", etc.). If the list was generated by a [[#Variations|variation]] then the "grouping" pin is also available.
|}

The following example shows how to define these values.
<epp:phrase id="viewname_eprint_divisions">Divisions</epp:phrase>
<epp:phrase id="viewtitle_eprint_divisions_menu_1">
Browse by Division and Year</epp:phrase>
<epp:phrase id="viewtitle_eprint_divisions_menu_2">
Browse by Year where Division is
<epc:pin name="value1" /> </epp:phrase>

==Other==

{|border="1" cellpadding="4" cellspacing="0"
|heading_level
| ?
|-
|include
| ?
|-
|subheadings
| ?
|-
|nohtml
| ?
|-
|noindex
| ?
|}

=Example=
==EPrints 3.2 example==
===cfg/cfg.d/views.pl===
{ id => "target", # The 'name' for this view
allow_null => 0,
hide_empty => 1,
menus => [
{ fields => ["broker_reponame"], # The field(s) to use - in this case the 'reponame' sub-element of the 'broker' field
new_column_at => [0], # force 2 columns, even if the
# second is blank
mode => "sections",
open_first_section => 1,
group_range_function => "EPrints::Update::Views::cluster_ranges_30",
group_sorting_function => "EPrints::Update::Views::default_sort",
},
],
order => "-date/title",
citation => 'router', # This defines the file in cfg/citations/eprint/
layout => 'router', # This is used in Views.pm to determine how to
# join individual citations together...
},

This creates a view, which will be 2-columns wide.
Two important definitions here are:
* '''citation''' defines the citation file used to create the block of html for each record to be displayed, and
* '''layout''' indicates how those blocks are joined together.

====Layout====
'''Layout''' can be one of:
* paragraph (the default)
puts elements round each citation

* orderedlist
makes an ordered list (1,2,3,4 or whatever the CSS defines)

* unorderedlist
makes an unordered list

* ''anything else''
just puts a newline (in the page source) after each citation

====citation====
In our example, we're using a home-made citation layout

The citation file is in <code>/cfg/citations/eprint/</code>

In the above view, we have defined the citation format to be '''router''', therefore we need a file called '''router.xml''' in the citations directory.

Remember this format is used for each record, so needs to be complete in it's own right - and if you want records to line up vertically, you need to plan that in advance.

<?xml version="1.0" ?>

<cite:citation xmlns:xhtml="http://www.w3.org/1999/xhtml" xmlns="http://eprints.org/ep3/control" xmlns:cite="http://eprints.org/ep3/citation" >
<table class='ep_rt_citation'>;
<tr><td colspan='2'>
<choose>
<when test="type = 'book' and is_set( creators )">
<print expr="creators_name"/>
</when>
.... more code ....
</choose>
</td><td style="width:8em">
<if test="date">(<print expr="date" opts="res=year"/>)</if>
</td></tr>
<tr><td style="width:50%">
<cite:linkhere><xhtml:em><print expr="title" opts="magicstop"/></xhtml:em></cite:linkhere>
</td>
<choose>
.... more code
<when test="type = 'article'">
<td>
<if test="publication"><print expr="publication"/>
<if test="volume">, <print expr="volume"/></if>
<if test="number"> (<print expr="number"/>)</if>
.</if>
<if test="pagerange"> <print expr="pagerange"/>.</if>
</td><td>
<if test="issn"> ISSN <print expr="issn"/></if>
</td>
</when>
.... more code
</choose>
</tr>
<if test=" ! type.one_of( 'patent','thesis' )">
<if test="ispublished.one_of('unpub', 'submitted', 'inpress')">
<tr><td colspan='2'>
(<print expr="ispublished"/>)
</td></tr>
</if>
</if>
</table>
</cite:citation>

This creates a table for each record, and CSS is used to manage the size & position of the various elements

===cfg/cfg.d/eprint_render.pl===
When viewing a record, the main abstract view page can also be altered

In <code>cfg/cfg.d/eprint_render.pl</code>, towards the bottom of the subroutine <code>$c->{eprint_render}</code> is the following line:

my $page = $eprint->render_citation( "router_page", %fragments, flags=>$flags );

Here, '''router_page''' is the name of the citation file for creating the abstract page..... '''router_page.xml''' in this case

Views.pl

2015-03-06T15:24:47Z

Kiz:

SWORD 2.0

2015-01-21T15:10:09Z

Kiz:

[[SWORD]] 2.0 is the default implimentation in EPrints 3.3, however there is a plugin to enable SWORD 1.3 (but see below)

== Terminology ==

SWORD 2.0 uses some specific terms for specific meanings
* '''collection''' The specific URL within the server for the data to go into. For EPrints this generally means inbox, review, archive, deleted - however for DSpace, there is a Collection concept; and Fedora has a similar RDF tag for defining collective groupings.
* '''package''' The URI that identifies how a particular deposit has been wrapped up.
** (eg <code>http://opendepot.org/broker/1.0</code>)
* '''content-type''' A ''mime-type'' (usually vendor specific) which the server recognises as triggering a particular process for handling the deposit process (very important in CRUD systems).
** (eg <code>application/vnd.rjbroker</code>)
* '''servicedocument''' The document that the SWORD server can return to inform clients of what collections and what packages are understood by the service

== Configuring SWORD ==

No configuration is required - SWORD 2.0 is enabled by default.
There are some caveats you need to be aware of:
* There is only one '''collection''': <code>/id/contents</code>
** All updates are done by naming the specific eprint ID
* By default, new records are created in the "review" buffer
** If the incoming request has the '''In-Progress''' header element set true, then the deposit will be put into the <code>inbox</code>
** If the repository has been configured to '''skip_buffer''' then items will be put into the <code>archive</code> buffer rather than <code>review</code>

== servicedocument ==

The servicedocument is an XML listing of what content-types (and packages) the server understands.

It no longer lists Q-Values.

The default location for the servicedocument is <tt>/sword-app/servicedocument</tt>

'''NOTE''' If you install the SWORD 1.3 plugin into EPrints 3.3, then <tt>/sword-app/servicedocument</tt> returns the SWORD 1.3 configuration, not the SWORD 2.0 information.

=== example ===
Below is an example framework of the servicedocument
<pre>
<?xml version='1.0' encoding='UTF-8'?>
<service xmlns="http://www.w3.org/2007/app" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:sword="http://purl.org/net/sword/"
xmlns:dcterms="http://purl.org/dc/terms/">
<workspace>
<atom:title>3.3.5: Manage deposits</atom:title>
<sword:version>2.0</sword:version>
<collection href="http://devel.edina.ac.uk:1202/id/contents">
<atom:title>Eprints</atom:title>
<sword:mediation>true</sword:mediation>
</collection>
</workspace>
</service>
</pre>

and the list of accepted content is given thus:
<pre>
<accept alternate="multipart-related">application/vnd.eprints.data+xml; charset=utf-8</accept>
<acceptPackaging>http://eprints.org/ep2/data/2.0</acceptPackaging>
<accept alternate="multipart-related">application/zip</accept>
<accept alternate="multipart-related">application/x-gzip</accept>
<acceptPackaging>http://purl.org/net/sword/package/SimpleZip</acceptPackaging>
<accept alternate="multipart-related">application/vnd.openxmlformats-officedocument.wordprocessingml.document</accept>
<accept alternate="multipart-related">application/vnd.openxmlformats</accept>
<accept alternate="multipart-related">application/msword</accept>
<accept alternate="multipart-related">application/vnd.rjbroker</accept>
<acceptPackaging>http://opendepot.org/broker/1.0</acceptPackaging>
<acceptPackaging>http://purl.org/net/sword/package/Binary</acceptPackaging>
<accept alternate="multipart-related">application/octet-stream</accept>
</pre>

Notice that there are a mixture of '''package''' and multi-part mime-types listed.

== Writing your own Importer ==

In EPrints 3.3, all importers are in the same place, there is no longer a distinction between "SWORD" and anything else.

As with all non-core code, importers are in <tt>~~eprints/lib/plugins/EPrints/Plugin/Import</tt>. As this is global to all repositories (in fact, all perl packages were visible to all repos under 3.2 too... the joys of Mod-Perl) plugins under <tt>lib</tt> are disabled by default

You can initially develop code in <tt>~~eprints/perl-lib/EPrints/Plugin/Import/</tt> however this is non-portable, and liable to get lost if (when!) you upgrade your installation of EPrints.

Assuming you start out creating an EPrints Package, then you need to read [[My_First_Bazaar_Package]]

# The actual package that handles the file being deposited
** This live in <tt>~~eprints/lib/plugins/EPrints/Plugin/Import/</tt>
** For complex importers, you may end up writing multiple packages - its Perl.... TMTOWTDI
# You need to configure the specific repository to enable the new package
** This lives in <tt>~~eprints/lib/epm/<Bazaar_package_name>/cfg/cfg.d/</tt>

=== Configuration file ===
This is simply an enabling statement - for example:

<pre>
# Ensure the plugin is enabled
$c->{plugins}->{"Import::RJ_Broker_2"}->{params}->{disable} = 0;
</pre>
Note that, whilst the actual perl package is Eprints/Plugin/Import/Foo.pm, and will be called <tt>EPrints::Plugin::Import::Foo</tt>, the configuration file already knows its a plugin that's being enabled, so only needs <tt>Import::Foo</tt>

=== 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::Import::MyImporter</code> will inherit most of its code from <code>EPrints::Plugin::Import</code>
# <code>EPrints::Plugin::Import</code> is a ''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/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::Import::RJ_Broker_2;

use strict;

use EPrints::Plugin::Import::Binary;
use EPrints::Plugin::Import::Archive;

our @ISA = qw/ EPrints::Plugin::Import::Archive /;

sub new
{
my ( $class, %params ) = @_;

my $self = $class->SUPER::new(%params);

# The name to display
$self->{name} = "RJ_Broker package";

# Who can see it, and whether we show it
$self->{visible} = "all";
$self->{advertise} = 1;

# What the importer produces
$self->{produce} = [qw( list/eprint dataobj/eprint )];

# What mime-types can trigger this importer
$self->{accept} = [ "application/vnd.rjbroker",
"sword:http://opendepot.org/broker/1.0" ];

return $self;
} ## end sub new

1;
</pre>
This defines a few important things:
<pre>
$self->{name} = "RJ_Broker package";
</pre>
is the name to display in public

<pre>
# What the importer produces
$self->{produce} = [qw( list/eprint dataobj/eprint )];
</pre>
defines what the importer actually returns (some handle specific files [.pdf, .doc, .mp3], others may import several records in one go [eg EndNote files])

<pre>
# What mime-types can trigger this importer
$self->{accept} = [ "application/vnd.rjbroker",
"sword:http://opendepot.org/broker/1.0" ];
</pre>
Defines what content-types andh/or package-types trigger the use of this importer.
(two importers registering to handle the same content-type is A bad Thing[tm]

Whilst this is pretty, it's actually pretty useless as all it will do is replicate what <tt>Import::Archive</tt> does. 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_fh</code>, and it will have a framework something like:

<pre>
sub input_fh
{
my ( $plugin, %opts ) = @_;

my $fh = $opts{fh};
my $dataset = $opts{dataset};
my $repo = $plugin->{session};

# get the type of file (should be zip) and the filename ($zipfile) for
# the file just deposited.
# (local method)
my $zipfile = $plugin->upload_archive($fh);

## Do magic to get the XML file with the metadata
my $epdata = $plugin->parse_epdcx_xml_data($xml_data);

my $dataobj = $plugin->epdata_to_dataobj( $dataset, $epdata );
if ( defined $dataobj ) {
push @ids, $dataobj->get_id;
}

return EPrints::List->new(
dataset => $dataset,
session => $repo,
ids => \@ids
);

}

sub upload_archive
{
my ( $self, $fh ) = @_;

use bytes;

binmode($fh);

my $zipfile = File::Temp->new();
binmode($zipfile);

my $rc;
my $lead;
while ( $rc = sysread( $fh, my $buffer, 4096 ) ) {
$lead = $buffer if !defined $lead;
syswrite( $zipfile, $buffer );
}
EPrints->abort("Error reading from file handle: $!") if !defined $rc;

return $zipfile;
} ## end sub upload_archive

sub parse_epdcx_xml_data
{
my ( $plugin, $xml ) = @_;

my $epdata = {};

## parse the XML as needed...

return $epdata;
} ## end sub parse_epdcx_xml_data

</pre>

==Depositing (from Perl)==

A SWORD deposit is, at its most basic level, just an HTTP POST request, so can be scripted fairly easily.

This is an example of an initial deposit, where the content being posted is a bespoke format

<pre>
# $ep is eprint to transfer
my $ua = LWP::UserAgent->new;
my $auth = "Basic " . MIME::Base64::encode( "$username:$password", '' );

my %headers = (
'X-No-Op' => 'false',
'X-Verbose' => 'true',
'Content-Disposition' => "filename=$filename", # The name of the "file" to be importer things its reading
'Content-Type' => $mime, # This triggers what parses the content. eg: application/vnd.rjbroker
'User-Agent' => 'OA-RJ Broker v0.2',
'Authorization' => $auth,
);

if ($in_progress) {
$headers{'in_progress'} = 'true' # Pushes into "inbox" rather than "review"
}

my $url = "${host}${collection}"; # eg: http://eprints.example.com/id/contents
my $buffer = $ep->export($exporter) # eg: Bespoke_Export_Routine (as in EPrints::Export::Bespoke_Export_Routine)

my $r = $ua->post( $url, %headers, Content => $buffer );
if ( $r->is_success ) {
# Transferred
my $content = $r->content;
my $return_id;
if ( $content =~ m#<id>([^<]+)</id># ) {
$return_id = $1 if $1;
}
} else {
# fail
}
</pre>

SWORD 1.3

2015-01-21T15:08:51Z

Kiz: /* Depositing (from Perl) */

[[SWORD]] 1.3 is the only option in EPrints 3.2, and is available via an EPrints bazaar plugin in EPrints 3.3

== Terminology ==

SWORD 1.3 uses some specific terms for specific meanings
* '''collection''' The specific URL within the server for the data to go into. For EPrints this generally means inbox, review, archive, deleted - however for DSpace, there is a Collection concept; and Fedora has a similar RDF tag for defining collective groupings.
* '''package''' The URI that identifies how a particular deposit has been wrapped up.
** (eg <code>http://opendepot.org/broker/1.0</code>)
* '''mediation''' This is where one user can deposit ''on behalf of'' another user.
* '''servicedocument''' The document that the SWORD server can return to inform clients of what collections and what packages are understood by the service

== Protocol implementation ==

verbose
no-op

== Configuring SWORD ==

The default location for SWORD configuration is

archives/<your repo>/cfg/cfg.d/sword.pl

This is where you enable and disable access to various ''collections'', and add/remove ''packages''

== servicedocument ==

The servicedocument is an XML listing of which "collections" are available, and what "packages" can be used with each one.

* a "collection" in EPrints terms is <tt>inbox</tt>, <tt>review</tt>, <tt>archive</tt> - which correspond to the users workspace, the administration review buffer, and visible in the live repository
* a "package" is an agreed method for wrapping up the data being sent over - as XML, as formatted text, in a zip file, etc...

The default location for the servicedocument is <tt>/sword-app/servicedocument</tt>

=== example ===
Below is an example framework of the servicedocument
<pre>
<service xmlns="http://www.w3.org/2007/app" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:sword="http://purl.org/net/sword/"
xmlns:dcterms="http://purl.org/dc/terms/">
<workspace>
<atom:title>OpenDepot.org</atom:title>
<collection href="http://opendepot.org/sword-app/deposit/buffer">
....
</collection>
<collection href="http://opendepot.org/sword-app/deposit/inbox">
....
</collection>
</workspace>
</pre>

and in each collection is listed for package formats unsderstood:
<pre>
<collection href="http://opendepot.org/sword-app/deposit/buffer">
<atom:title>Repository Review</atom:title>
<accept>*/*</accept>
<sword:acceptPackaging q="0.2">http://www.loc.gov/METS/</sword:acceptPackaging>
<sword:acceptPackaging q="1.0">http://eprints.org/ep2/data/2.0</sword:acceptPackaging>
<sword:acceptPackaging q="0.2">http://www.imsglobal.org/xsd/imscp_v1p1</sword:acceptPackaging>
<sword:acceptPackaging q="0.2">http://purl.org/net/sword-types/METSDSpaceSIP</sword:acceptPackaging>
<sword:collectionPolicy/>
<sword:treatment>
Deposited items will undergo the review process. Upon approval, items will appear in the live repository.
</sword:treatment>
<sword:mediation>true</sword:mediation>
<dcterms:abstract>This is the repository review.</dcterms:abstract>
</collection>
</pre>

== 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>

==Depositing (from Perl)==

A SWORD deposit is, at its most basic level, just an HTTP POST request, so can be scripted fairly easily:

<pre>
# $ep is eprint to transfer
my $ua = LWP::UserAgent->new;
my $auth = "Basic " . MIME::Base64::encode( "$username:$password", '' ); # eg: sworduser:mySecretPassword

my %headers = (
'X-Packaging' => $package, # eg: http://opendepot.org/broker/1.0
'X-No-Op' => 'false',
'X-Verbose' => 'true',
'Content-Disposition' => "filename=$filename", # The name of the "file" to be importer things its reading
'Content-Type' => $mime, # eg: application/zip
'User-Agent' => 'OA-RJ Broker v0.2',
'Authorization' => $auth,
);
my $url = "${host}${collection}"; # eg: http://eprints.example.com/sword-app/deposit/review
my $buffer = $ep->export($exporter) # eg BibTeX (as in EPrints::Export::BibTeX)

my $r = $ua->post( $url, %headers, Content => $buffer );
if ( $r->is_success ) {
# Transferred
my $content = $r->content;
my $return_id;
if ( $content =~ m#<atom:id>([^<]+)</atom:id># ) {
$return_id = $1 if $1;
}
} else {
# fail
}
</pre>

SWORD 1.3

2015-01-21T15:05:00Z

Kiz: /* Depositing (from Perl) */

[[SWORD]] 1.3 is the only option in EPrints 3.2, and is available via an EPrints bazaar plugin in EPrints 3.3

== Terminology ==

SWORD 1.3 uses some specific terms for specific meanings
* '''collection''' The specific URL within the server for the data to go into. For EPrints this generally means inbox, review, archive, deleted - however for DSpace, there is a Collection concept; and Fedora has a similar RDF tag for defining collective groupings.
* '''package''' The URI that identifies how a particular deposit has been wrapped up.
** (eg <code>http://opendepot.org/broker/1.0</code>)
* '''mediation''' This is where one user can deposit ''on behalf of'' another user.
* '''servicedocument''' The document that the SWORD server can return to inform clients of what collections and what packages are understood by the service

== Protocol implementation ==

verbose
no-op

== Configuring SWORD ==

The default location for SWORD configuration is

archives/<your repo>/cfg/cfg.d/sword.pl

This is where you enable and disable access to various ''collections'', and add/remove ''packages''

== servicedocument ==

The servicedocument is an XML listing of which "collections" are available, and what "packages" can be used with each one.

* a "collection" in EPrints terms is <tt>inbox</tt>, <tt>review</tt>, <tt>archive</tt> - which correspond to the users workspace, the administration review buffer, and visible in the live repository
* a "package" is an agreed method for wrapping up the data being sent over - as XML, as formatted text, in a zip file, etc...

The default location for the servicedocument is <tt>/sword-app/servicedocument</tt>

=== example ===
Below is an example framework of the servicedocument
<pre>
<service xmlns="http://www.w3.org/2007/app" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:sword="http://purl.org/net/sword/"
xmlns:dcterms="http://purl.org/dc/terms/">
<workspace>
<atom:title>OpenDepot.org</atom:title>
<collection href="http://opendepot.org/sword-app/deposit/buffer">
....
</collection>
<collection href="http://opendepot.org/sword-app/deposit/inbox">
....
</collection>
</workspace>
</pre>

and in each collection is listed for package formats unsderstood:
<pre>
<collection href="http://opendepot.org/sword-app/deposit/buffer">
<atom:title>Repository Review</atom:title>
<accept>*/*</accept>
<sword:acceptPackaging q="0.2">http://www.loc.gov/METS/</sword:acceptPackaging>
<sword:acceptPackaging q="1.0">http://eprints.org/ep2/data/2.0</sword:acceptPackaging>
<sword:acceptPackaging q="0.2">http://www.imsglobal.org/xsd/imscp_v1p1</sword:acceptPackaging>
<sword:acceptPackaging q="0.2">http://purl.org/net/sword-types/METSDSpaceSIP</sword:acceptPackaging>
<sword:collectionPolicy/>
<sword:treatment>
Deposited items will undergo the review process. Upon approval, items will appear in the live repository.
</sword:treatment>
<sword:mediation>true</sword:mediation>
<dcterms:abstract>This is the repository review.</dcterms:abstract>
</collection>
</pre>

== 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>

==Depositing (from Perl)==

A SWORD deposit is, at its most basic level, just an HTTP POST request, so can be scripted fairly easily:

<pre>
# $ep is eprint to transfer
my $ua = LWP::UserAgent->new;
my $auth = "Basic " . MIME::Base64::encode( "$username:$password", '' ); # eg: sworduser:mySecretPassword

my %headers = (
'X-Packaging' => $package, # eg: http://opendepot.org/broker/1.0
'X-No-Op' => 'false',
'X-Verbose' => 'true',
'Content-Disposition' => "filename=$filename", # The name of the "file" to be importer things its reading
'Content-Type' => $mime, # eg: application/zip
'User-Agent' => 'OA-RJ Broker v0.2',
'Authorization' => $auth,
);
my $url = "${host}${collection}"; # eg: http://eprints.example.com/sword-app/deposit/review
my $buffer = $ep->export($exporter) # eg BibTeX

my $r = $ua->post( $url, %headers, Content => $buffer );
if ( $r->is_success ) {
# Transferred
my $content = $r->content;
my $return_id;
if ( $content =~ m#<atom:id>([^<]+)</atom:id># ) {
$return_id = $1 if $1;
}
} else {
# fail
}
</pre>

SWORD 1.3

2015-01-21T14:58:15Z

Kiz:

[[SWORD]] 1.3 is the only option in EPrints 3.2, and is available via an EPrints bazaar plugin in EPrints 3.3

== Terminology ==

SWORD 1.3 uses some specific terms for specific meanings
* '''collection''' The specific URL within the server for the data to go into. For EPrints this generally means inbox, review, archive, deleted - however for DSpace, there is a Collection concept; and Fedora has a similar RDF tag for defining collective groupings.
* '''package''' The URI that identifies how a particular deposit has been wrapped up.
** (eg <code>http://opendepot.org/broker/1.0</code>)
* '''mediation''' This is where one user can deposit ''on behalf of'' another user.
* '''servicedocument''' The document that the SWORD server can return to inform clients of what collections and what packages are understood by the service

== Protocol implementation ==

verbose
no-op

== Configuring SWORD ==

The default location for SWORD configuration is

archives/<your repo>/cfg/cfg.d/sword.pl

This is where you enable and disable access to various ''collections'', and add/remove ''packages''

== servicedocument ==

The servicedocument is an XML listing of which "collections" are available, and what "packages" can be used with each one.

* a "collection" in EPrints terms is <tt>inbox</tt>, <tt>review</tt>, <tt>archive</tt> - which correspond to the users workspace, the administration review buffer, and visible in the live repository
* a "package" is an agreed method for wrapping up the data being sent over - as XML, as formatted text, in a zip file, etc...

The default location for the servicedocument is <tt>/sword-app/servicedocument</tt>

=== example ===
Below is an example framework of the servicedocument
<pre>
<service xmlns="http://www.w3.org/2007/app" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:sword="http://purl.org/net/sword/"
xmlns:dcterms="http://purl.org/dc/terms/">
<workspace>
<atom:title>OpenDepot.org</atom:title>
<collection href="http://opendepot.org/sword-app/deposit/buffer">
....
</collection>
<collection href="http://opendepot.org/sword-app/deposit/inbox">
....
</collection>
</workspace>
</pre>

and in each collection is listed for package formats unsderstood:
<pre>
<collection href="http://opendepot.org/sword-app/deposit/buffer">
<atom:title>Repository Review</atom:title>
<accept>*/*</accept>
<sword:acceptPackaging q="0.2">http://www.loc.gov/METS/</sword:acceptPackaging>
<sword:acceptPackaging q="1.0">http://eprints.org/ep2/data/2.0</sword:acceptPackaging>
<sword:acceptPackaging q="0.2">http://www.imsglobal.org/xsd/imscp_v1p1</sword:acceptPackaging>
<sword:acceptPackaging q="0.2">http://purl.org/net/sword-types/METSDSpaceSIP</sword:acceptPackaging>
<sword:collectionPolicy/>
<sword:treatment>
Deposited items will undergo the review process. Upon approval, items will appear in the live repository.
</sword:treatment>
<sword:mediation>true</sword:mediation>
<dcterms:abstract>This is the repository review.</dcterms:abstract>
</collection>
</pre>

== 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>

==Depositing (from Perl)==

A SWORD deposit is, at its most basic level, just an HTTP POST request, so can be scripted fairly easily:

<pre>
# $ep is eprint to transfer
my $ua = LWP::UserAgent->new;
my $auth = "Basic " . MIME::Base64::encode( "$username:$password", '' );

my %headers = (
'X-Packaging' => $package, # eg: http://opendepot.org/broker/1.0
'X-No-Op' => 'false',
'X-Verbose' => 'true',
'Content-Disposition' => "filename=$filename", # The name of the "file" to be importer things its reading
'Content-Type' => $mime, # eg: application/zip
'User-Agent' => 'OA-RJ Broker v0.2',
'Authorization' => $auth,
);
my $url = "${host}${collection}";
my $buffer = $ep->export($exporter) # eg BibTeX

my $r = $ua->post( $url, %headers, Content => $buffer );
if ( $r->is_success ) {
# Transferred
my $content = $r->content;
my $return_id;
if ( $content =~ m#<atom:id>([^<]+)</atom:id># ) {
$return_id = $1 if $1;
}
} else {
# fail
}
</pre>

2013-10-17T15:50:00Z

Kiz: Created page with 'SWORD 2.0 is the default implimentation in EPrints 3.3, however there is a plugin to enable SWORD 1.3 (but see below) == Terminology == SWORD 2.0 uses some specific terms f…'

[[SWORD]] 2.0 is the default implimentation in EPrints 3.3, however there is a plugin to enable SWORD 1.3 (but see below)

== Terminology ==

SWORD 2.0 uses some specific terms for specific meanings
* '''collection''' The specific URL within the server for the data to go into. For EPrints this generally means inbox, review, archive, deleted - however for DSpace, there is a Collection concept; and Fedora has a similar RDF tag for defining collective groupings.
* '''package''' The URI that identifies how a particular deposit has been wrapped up.
** (eg <code>http://opendepot.org/broker/1.0</code>)
* '''content-type''' A ''mime-type'' (usually vendor specific) which the server recognises as triggering a particular process for handling the deposit process (very important in CRUD systems).
** (eg <code>application/vnd.rjbroker</code>)
* '''servicedocument''' The document that the SWORD server can return to inform clients of what collections and what packages are understood by the service

== Configuring SWORD ==

No configuration is required - SWORD 2.0 is enabled by default.
There are some caveats you need to be aware of:
* There is only one '''collection''': <code>/id/contents</code>
** All updates are done by naming the specific eprint ID
* By default, new records are created in the public archive
* If a deposit has an issue (such as missing metadata fields flagged as ''required'') then the deposits are put into the review queue

'''NOTE''' - Need to work out how one uses "status" - can it direct a ''create'' into a particular buffer?)

== servicedocument ==

The servicedocument is an XML listing of what content-types (and packages) the server understands.

It no longer lists Q-Values.

The default location for the servicedocument is <tt>/sword-app/servicedocument</tt>

=== example ===
Below is an example framework of the servicedocument
<pre>
<?xml version='1.0' encoding='UTF-8'?>
<service xmlns="http://www.w3.org/2007/app" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:sword="http://purl.org/net/sword/" xmlns:dcterms="http://purl.org/dc/terms/">
<workspace>
<atom:title>3.3.5: Manage deposits</atom:title>
<sword:version>2.0</sword:version>
<collection href="http://devel.edina.ac.uk:1202/id/contents">
<atom:title>Eprints</atom:title>
<sword:mediation>true</sword:mediation>
</collection>
</workspace>
</service>
</pre>

and the list of accepted content is given thus:
<pre>
<accept alternate="multipart-related">application/vnd.eprints.data+xml; charset=utf-8</accept>
<acceptPackaging>http://eprints.org/ep2/data/2.0</acceptPackaging>
<accept alternate="multipart-related">application/zip</accept>
<accept alternate="multipart-related">application/x-gzip</accept>
<acceptPackaging>http://purl.org/net/sword/package/SimpleZip</acceptPackaging>
<accept alternate="multipart-related">application/vnd.openxmlformats-officedocument.wordprocessingml.document</accept>
<accept alternate="multipart-related">application/vnd.openxmlformats</accept>
<accept alternate="multipart-related">application/msword</accept>
<accept alternate="multipart-related">application/vnd.rjbroker</accept>
<acceptPackaging>http://opendepot.org/broker/1.0</acceptPackaging>
<acceptPackaging>http://purl.org/net/sword/package/Binary</acceptPackaging>
<accept alternate="multipart-related">application/octet-stream</accept>
</pre>

Notice that there are a mixture of '''package''' and multi-part mime-types listed.

== Writing your own Importer ==

In EPrints 3.3, all importers are in the same place, there is no longer a distinction between "SWORD" and anything else.

As with all non-core code, importers are in <tt>~~eprints/lib/plugins/EPrints/Plugin/Import</tt>. As this is global to all repositories (in fact, all perl packages were visible to all repos under 3.2 too... the joys of Mod-Perl) plugins under <tt>lib</tt> are disabled by default

You can initially develop code in <tt>~~eprints/perl-lib/EPrints/Plugin/Import/</tt> however this is non-portable, and liable to get lost if (when!) you upgrade your installation of EPrints.

Assuming you start out creating an EPrints Package, then you need to read [[My_First_Bazaar_Package]]

# The actual package that handles the file being deposited
** This live in <tt>~~eprints/lib/plugins/EPrints/Plugin/Import/</tt>
** For complex importers, you may end up writing multiple packages - its Perl.... TMTOWTDI
# You need to configure the specific repository to enable the new package
** This lives in <tt>~~eprints/lib/epm/<Bazaar_package_name>/cfg/cfg.d/</tt>

=== Configuration file ===
This is simply an enabling statement - for example:

<pre>
# Ensure the plugin is enabled
$c->{plugins}->{"Import::RJ_Broker_2"}->{params}->{disable} = 0;
</pre>
Note that, whilst the actual perl package is Eprints/Plugin/Import/Foo.pm, and will be called <tt>EPrints::Plugin::Import::Foo</tt>, the configuration file already knows its a plugin that's being enabled, so only needs <tt>Import::Foo</tt>

=== 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::Import::MyImporter</code> will inherit most of its code from <code>EPrints::Plugin::Import</code>
# <code>EPrints::Plugin::Import</code> is a ''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/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::Import::RJ_Broker_2;

use strict;

use EPrints::Plugin::Import::Binary;
use EPrints::Plugin::Import::Archive;

our @ISA = qw/ EPrints::Plugin::Import::Archive /;

sub new {
my ( $class, %params ) = @_;

my $self = $class->SUPER::new(%params);

# The name to display
$self->{name} = "RJ_Broker package";

# Who can see it, and whether we show it
$self->{visible} = "all";
$self->{advertise} = 1;

# What the importer produces
$self->{produce} = [qw( list/eprint dataobj/eprint )];

# What mime-types can trigger this importer
$self->{accept} = [ "application/vnd.rjbroker",
"sword:http://opendepot.org/broker/1.0" ];

return $self;
} ## end sub new

1;
</pre>
This defines a few important things:
<pre>
$self->{name} = "RJ_Broker package";
</pre>
is the name to display in public

<pre>
# What the importer produces
$self->{produce} = [qw( list/eprint dataobj/eprint )];
</pre>
defines what the importer actually returns (some handle specific files [.pdf, .doc, .mp3], others may import several records in one go [eg EndNote files])

<pre>
# What mime-types can trigger this importer
$self->{accept} = [ "application/vnd.rjbroker",
"sword:http://opendepot.org/broker/1.0" ];
</pre>
Defines what content-types andh/or package-types trigger the use of this importer.
(two importers registering to handle the same content-type is A bad Thing[tm]

Whilst this is pretty, it's actually pretty useless as all it will do is replicate what <tt>Import::Archive</tt> does. 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_fh</code>, and it will have a framework something like:

<pre>
sub input_fh {
my ( $plugin, %opts ) = @_;

my $fh = $opts{fh};
my $dataset = $opts{dataset};
my $repo = $plugin->{session};

# get the type of file (should be zip) and the filename ($zipfile) for
# the file just deposited.
# (local method)
my ( $type, $zipfile ) = $plugin->upload_archive($fh);

## Do magic to get the XML file with the metadata
my $epdata = $plugin->parse_epdcx_xml_data($xml_data);

my $dataobj = $plugin->epdata_to_dataobj( $dataset, $epdata );
if ( defined $dataobj ) {
push @ids, $dataobj->get_id;
}

return EPrints::List->new(
dataset => $dataset,
session => $repo,
ids => \@ids
);

}

## add in the upload_archive & arse_epdcx_xml_data methods
</pre>

SWORD 1.3

2013-10-17T14:52:44Z

Kiz:

SWORD 1.3

2013-10-17T14:25:27Z

Kiz: Created page with 'SWORD 1.3 is the only option in EPrints 3.2, and is available via an EPrints bazaar plugin in EPrints 3.3 == Terminology == SWORD 1.3 uses some specific terms for specific mean…'

SWORD 1.3 is the only option in EPrints 3.2, and is available via an EPrints bazaar plugin in EPrints 3.3

== Terminology ==

SWORD 1.3 uses some specific terms for specific meanings
* '''collection''' The specific URL within the server for the data to go into. For EPrints this generally means inbox, review, archive, deleted - however for DSpace, there is a Collection concept; and Fedora has a similar RDF tag for defining collective groupings.
* '''package''' The URI that identifies how a particular deposit has been wrapped up.
** (eg <code>http://opendepot.org/broker/1.0</code>)
* '''mediation''' This is where one user can deposit ''on behalf of'' another user.
* '''servicedocument''' The document that the SWORD server can return to inform clients of what collections and what packages are understood by the service

== Protocol implementation ==

verbose
no-op

== Configuring SWORD ==

The default location for SWORD configuration is

archives/<your repo>/cfg/cfg.d/sword.pl

This is where you enable and disable access to various ''collections'', and add/remove ''packages''

== servicedocument ==

The servicedocument is an XML listing of which "collections" are available, and what "packages" can be used with each one.

* a "collection" in EPrints terms is <tt>inbox</tt>, <tt>review</tt>, <tt>archive</tt> - which correspond to the users workspace, the administration review buffer, and visible in the live repository
* a "package" is an agreed method for wrapping up the data being sent over - as XML, as formatted text, in a zip file, etc...

The default location for the servicedocument is <tt>/sword-app/servicedocument</tt>

=== example ===
Below is an example framework of the servicedocument
<pre>
<service xmlns="http://www.w3.org/2007/app" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:sword="http://purl.org/net/sword/"
xmlns:dcterms="http://purl.org/dc/terms/">
<workspace>
<atom:title>OpenDepot.org</atom:title>
<collection href="http://opendepot.org/sword-app/deposit/buffer">
....
</collection>
<collection href="http://opendepot.org/sword-app/deposit/inbox">
....
</collection>
</workspace>
</pre>

and in each collection is listed for package formats unsderstood:
<pre>
<collection href="http://opendepot.org/sword-app/deposit/buffer">
<atom:title>Repository Review</atom:title>
<accept>*/*</accept>
<sword:acceptPackaging q="0.2">http://www.loc.gov/METS/</sword:acceptPackaging>
<sword:acceptPackaging q="1.0">http://eprints.org/ep2/data/2.0</sword:acceptPackaging>
<sword:acceptPackaging q="0.2">http://www.imsglobal.org/xsd/imscp_v1p1</sword:acceptPackaging>
<sword:acceptPackaging q="0.2">http://purl.org/net/sword-types/METSDSpaceSIP</sword:acceptPackaging>
<sword:collectionPolicy/>
<sword:treatment>
Deposited items will undergo the review process. Upon approval, items will appear in the live repository.
</sword:treatment>
<sword:mediation>true</sword:mediation>
<dcterms:abstract>This is the repository review.</dcterms:abstract>
</collection>
</pre>

== 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>

2013-10-11T15:30:39Z

Kiz: /* Supported packages */

2013-06-03T10:47:23Z

Kiz:

Non-root proxy

2013-05-29T07:52:49Z

Kiz: /* Preparation */

[[Category:Installation]]
===Task===
To build Apache 2 & mod_perl 2 for ePrints 3, installed as a standard user, with no superuser-like access to core services (including Perl and mySQL). The ePrints server will run as a normal user, and be accessed through a central proxy

===Preparation===

As we are installing software as a normal user (I'll use MyUser in this example), we are not adding any additional Perl modules centrally, but into a local tree. Cleverly, the Perl people have thought of this, and simply by running the <code>cpan</code> command for the first time will configure the whole thing for you!

<pre>

%> cpan

</pre>

When asked how you are installing Perl modules, the answer is <code>localLib</code>

===Now we can start installing software.===
====Apache====
Install a base Apache (previously downloaded into ~/distributions):
<pre>

%> cd ~/distributions/
%> tar xvf httpd-2.2.x.tar
%> cd httpd_2.2.x

</pre>
If you are returning to an existing source-tree, rather than a brand new untar'd bundle, clear any previous setup:
<pre>

%> make distclean

</pre>
Now configure and install an initial Apache server:
<pre>

%> ./configure --prefix=/home/MyUser/www --disable-userdir --disable-status
%> make
%> make install

</pre>

Edit http.conf (essentially, the port the server is listening on) and start the web server. Check the error log:

<pre>

%> cat ~/www/logs/error_log
[...] Apache/2.2.x (Unix) Configured -- resuming normal operations

</pre>

====Mod-Perl====
Stop web server and install the Mod-Perl extensions (previously downloaded into ~/distributions):
<pre>

%> cd ~/distributions/
%> tar xvf mod_perl-2.0-current.tar
%> cd mod_perl-2.0.x

</pre>

If you are returning to an existing source-tree, rather than a brand new untar'd bundle, clear any previous setup:
<pre>

%> make clean

</pre>
Now configure and install mod-perl into the Apache tree, and (re)install Apache. In this example, I am specifying a version of Perl to use:
<pre>

%> /path/to/specific/perl Makefile.PL PREFIX="/home/MyUser/perl5" MP_USE_DSO=1 \
MP_APXS="/home/MyUser/www/bin/apxs" \
MP_AP_CONFIGURE="--prefix=/home/MyUser/www --disable-userdir \
--disable-status --enable-module=mod-perl"
%> make
%> make install

</pre>

NOTE: Notice that there is a PREFIX defined, which matches the prefix in the CPAN configuration; that we are stating we want mod-perl as a DSO; the full path to the previously installed Apache "apxs" command; and that the configure parameters to be passed to the apache rebuild include enabling mod-perl

=====Editing the new apache config file=====
We need to enable the mod-perl module, which I do using one of the Includes:
* In ~/www/conf/httpd.conf, add:
<pre>

# Mod-Perl
Include conf/extra/httpd-perl.conf

</pre>

* Create ~/www/conf/extra/httpd-perl.conf:
<pre>

#
# Load the Mod_perl DSO.
#
LoadModule perl_module modules/mod_perl.so
PerlSwitches -I/home/MyUser/perl5/lib/perl5/site_perl/5.x.y/sun4-solaris/ \
-I/home/MyUser/perl5/lib/perl5/5.x.y/sun4-solaris \
-I/home/MyUser/perl5/lib/perl5/5.x.y \
-I/home/MyUser/perl5/lib/perl5/site_perl/5.x.y/sun4-solaris \
-I/home/MyUser/perl5/lib/perl5/site_perl/5.x.y \
-I/home/MyUser/perl5/lib/perl5/site_perl

</pre>

* NOTE: the "PerlSwitches" line tells the Apache server where to look for extra libraries, and matches the PERL5LIB environment variable set earlier.</dd>

Start the web server. Check the error log:

<pre>

%> cat ~/www/logs/error_log
[...] Apache/2.2.x (Unix) Configured -- resuming normal operations
[...] caught SIGTERM, shutting down
[...] Apache/2.2.x (Unix) mod_perl/2.0.x Perl/v5.x.y configured -- resuming normal operations

</pre>

Stop the web server again.
----

===ePrints===
Before you can install ePrints, you need to check the Package requirements.
CGI.pm builds against the installed Mod-Perl modules, so may well be wrong. You may need to install your own version.

eg:
<pre>

%> /path/to/specific/perl -MCPAN -e shell
[snip]
cpan> install CGI
[...]
cpan> quit

</pre>

Now we can install the ePrints software (previously downloaded into ~/distributions):

<pre>

%> cd ~/distributions/
%> tar xvf eprints-3.zzz.tar
%> cd eprints-3.zzz./

</pre>

There is no option to clean a previously configured eprints tree, so keep going..
<pre>

%> ./configure --prefix=/home/MyUser/ePrints --with-perl=/path/to/specific/perl --with-user=MyUser \
--with-group=MyUserGroup -with-toolpath=/path/to/tools --disable-diskfree \
--with-smtp-server=your.mail.server

</pre>

Note: the same version of perl is being defined again, and the <code>/path/to/tools</code> is a directory to find various external tools (<code>tar</code>, <code>wget</code>, <code>(g)unzip</code>, <code>pdftotext</code>, <code>lynx</code>, etc)

... and install:
<pre>

%> ./install.pl

</pre>

As we do not have root access to the MySQL database, you will need to get the database administrator to add a user to provide access the MySQL database. Note: Assuming your user is not given <code>GRANT ALL</code> (its a big security risk) you will need <code>CREATE TEMPORARY TABLES</code> as well as <code>CREATE</code> privilages.

====Create the basic repository====

The trick here is to install a basic eprint repository to match the web server (installed above), and then alter the core configuration to reflect the proxy settings.

<pre>

%> cd /home/MyUser/ePrints

</pre>

We also know that the service is going to run as a local user, so the file and directory permissions need to be altered

These are all defined in the file <code>perl_lib/EPrints/SystemSettings.pm</code>:
<pre>
$EPrints::SystemSettings::conf = {
// snip //
'file_perms' => 0640,
// snip //
'dir_perms' => 0775
</pre>

In EPrints 3, all the configuration is done using the <code>bin/epadmin</code>.

* Initial configuration

'''NOTE:''' EPrints assumes a MySql backend, and the configuration routines assume it. This means that you need to have the mysql libraries available to the perl routines during this process. You may setup a Postgres, Oracle, or "Cloud" storage system once the basic configuration is in place, but you need mysql to kick-start the process.

The command to create the basic framework for a repository is:

<pre>
bin/epadmin create
</pre>

* When asked <code>Configure vital settings? [yes] ?</code>, say "Yes" and fill in the details
** <code>Hostname?</code> is the actual address of the web server created above, not the public address (we fix that later)
** <code>Webserver Port [80] ?</code> is the actual address of the web server created above, not the port for the web server (we fix that later)
** <code>Archive Name [Test Repository] ?</code> is the name that the EPrints.org system will use when it dynamically supplies the archive name (using the <epc:pin /> coding)

* When asked <code>Configure database? [yes] ?</code>, say "Yes" and fill in the details
** <code>Database Name</code> is the name of the database created for you by the database admin people
** <code>MySQL Host</code> is the hostname for the server
** <code>MySQL Port</code> <code>MySQL Socket</code> can probably be left blank, but check with the database admin people
** <code>Database User</code> <code>Database Password</code> is as per agreed with the database admin people
* <code>Create database "Deposit"</code> NO - you can't, as we don't have that level of access to the database.

Now we need to do the rest of the building-work manually:

When using a database that's '''not''' mysql, then you need to tell EPrints what driver to use.
* Edit <pre> archives/<ARCHIVEID>/cfg/cfg.d/database.pl </pre> and add <pre> $c->{dbdriver} = "xxxx"; </pre> where '''xxx''' is the appropriate Perl DBD package (eg '''Pg''' for postgreSQL)

* Create the database tables: <pre> bin/epadmin create_tables <ARCHIVEID> </pre>
* Create users (I suggest an admin user and a normal user): <pre> bin/epadmin create_user <ARCHIVEID> </pre>
* Build the subject tables: <pre> bin/import_subjects <ARCHIVEID> <path/to/subject/file></pre> Either use <code>lib/defaultcfg/subjects</code> for the shipped '''Library Of Congress''' tree, or download a subject tree from [http://files.eprints.org files.eprints.org]
* Create the static web pages for a basic web site: <pre> bin/generate_static <ARCHIVEID> </pre>
* Create pages of abstracts: <pre> bin/generate_abstracts <ARCHIVEID> </pre> (should do nothing, as there are no abstracts in the system)
* Create the browse pages: <pre> bin/generate_views <ARCHIVEID> </pre>

====Configuring the repository:====

EPrints has a global Apache configuration file, and then separate config files for each <ARCHIVEID> archive running under the web server

To be sure of the correct config files for your particular install (we are discovering that they seem to move around depending on version), do the following command:

<pre> cd /home/MyUser/ePrints
find ./ -name *.conf -print
</pre>

Generate the apache configuration files.

<pre> cd /home/MyUser/ePrints
bin/generate_apacheconf </pre>

Edit httpd.conf to include the generated apache.conf:

<pre>

# EPrints
Include /home/MyUser/ePrints/cfg/apache.conf

</pre>

Remove the document root and cgi-bin stuff from the httpd.conf file (the name and the <directory> section)

Add access permissions to the <code><Directory "/home/MyUser/ePrints/cgi"></code> section in <code>ePrints/archives/<ARCHIVEID>/cfg/auto-apache.conf</code>:

<pre>

Order deny,allow
Allow from all

</pre>

EPrints produces absolute URLs for everything (<code>http://web.host.name/</code>), so we need to ensure that the repository uses the correct address. Edit <code>archives/ARCHIVEID/cfg/cfg.d/10_core.pl</code>
<pre>
$c->{host} = 'public.host.name.org';
$c->{port} = '80';

</pre>

====Fix a bug-ette====
There is a problem that has been found on a number of systems where the system goes into a loop of reporting
<pre> [warn] (128)Network is unreachable: connect to listener on [::]:<PORTNO></pre>

The solution is to alter the "Listen" directive to include an IP number. Either use the IP number for the host, or cheat:
<pre>
Listen: 0.0.0.0:<PORTNO>

</pre>

Start web server. Check the error log:

<pre>

%> cat ~/www/logs/error_log
[...] Apache/2.2.0 (Unix) Configured -- resuming normal operations
[...] caught SIGTERM, shutting down
[...] Apache/2.2.0 (Unix) mod_perl/2.0.2 Perl/v5.8.0 configured -- resuming normal operations
[...] [notice] caught SIGTERM, shutting down
EPrints archives loaded: <ARCHIVEID>
EPrints archives loaded: <ARCHIVEID>
[...] Apache/2.2.0 (Unix) mod_perl/2.0.2 Perl/v5.8.0 configured -- resuming normal operations

</pre>

===GLORY IN YOUR NEW EPRINTS SYSTEM!!!!===

To modify the general layout of the page, edit <code>ePrints/archives/<ARCHIVEID>/cfg/template-en.xml</code> and then re-run <code>.../bin/generate_static <ARCHIVEID></code>

2012-08-02T09:13:28Z

Kiz: /* Batch Edit */

[[Category:EPrints_Bazaar]]

This page offers an agenda for the 3 day Bazaar development event in Edinburgh 1-3 August 2012.

Location: EH9 1PR

Over the course of the days the aim is to test, document and better represent our selves in the bazaar store where things are already a little messy (slap wrists people). Through testing of packages we need to improve descriptions, icons and compliment the packages with screen shots to help our users.

=Day 1 - Wednesday 1st August 2012=

* Bazaar
** Package Improvement, Config, Dependancies, Documentation, Screenshot
*** Amazon S3
*** Green Spring
*** Batch Edit
*** Icon Builder

** Dependencies Ideas
** Bazaar Store Improvements - Seal of Approval, Screenshots, Tags, Display of Dependancies Field

* Core
** Loosing Data on Disable/Uninstall

===Green Spring===
* Capture screenshot

===Batch Edit===
* Installer fails to detect a lack of external dependencies: Spreadsheet::ParseExcel, Spreadsheet::WriteExcel
* Install is a silent fail
* Uninstall fails with a misleading error ("Repository configuration not reloaded. Errors in configuration files" rather than not actually active)

===EXIF Import===
* Captured screenshots
* Plugin description could be a bit less brief
* Plugin does not actually work
* There is a dependancy on IMAGE::Exif
* once that is installed the plugin still fails
* Unhandled warning in Import::EXIF: File not found: *Fh::fh00001bear.jpg
* Warning Import failed: 1 item(s) imported before an error caused the import to abort.

===Icon Builder===
* Installs without issue
* must navigate to cgi/icon_builder (this should probably be a screen plugin with a link in key_tools or the admin panels)
* you can upload a jpg and modify the baground colour.
* when you hit export the file it returns is not a vaild jpeg

===AmazonS3===
* Installed
* updated package to do dependancy checking and output appropriate error messages
* outputs help to configure after installation
* created an example storeage policy
* tested fully
* dave t and dave m took screen shots

===OREExport===
* Installed plugin
* Took screen shots
* Export works
* Import works

===SNEEP===
* Installed
* works
* Screenshots

===Schedule===
* 11:30 - A Simple Start, take the easy packages and improve and screen shot them.
* 12:30 - Lunch
* 13:30 - Complex Bazaar Package Testing
The idea here is to test the more complex packages (those that require dependencies outside of those needed by eprints) and work out how to best support our "one click" users in installing these packages. Additionally we should looks for packages that need config and make sure they have a "config" link!. These packages include:
** Coversheets
** Preservation Toolkit
** Tweepository
** Open Office Toolkit

=Day 2 - Thursday 2nd August 2012=

* 09:30 - Bazaar Store Upgrades & Package Testing
Put all the stuff from yesterday in the store.
** Screenshots
** Dependencies
** Descriptions
** Icons
* 11:00 - Languages Packs
Take the language packs from files and put them in the store.
* 12:30 - Lunch
* 13:30 - Package Fest

=Day 3 - Friday 3rd August 2012=
* Package Fest

[[File:DSC_0020.JPG|thumb]]

=Attendees=

* Les Carr - University of Southampton
* David Tarrant - University of Southampton
* Tim Brody - University of Southampton
* Patrick McSweeney - University of Southampton
* Matthew Taylor - University of Southampton
* Adam Field - University of Southampton

Please add your name ...

* Ian Stuart - EDINA
* David McElroy - University of Glasgow
* Dawid Pachla - University of Glasgow
* Chris Yocum - EDINA

=Packages of Interest=

DON'T TOUCH: Shelves, Coverpage, REF, eNova, Kultivate

Bazaar Edinburgh 2012

2012-08-02T09:00:55Z

Kiz: /* Day 1 - Wednesday 1st August 2012 */

[[Category:EPrints_Bazaar]]

This page offers an agenda for the 3 day Bazaar development event in Edinburgh 1-3 August 2012.

Location: EH9 1PR

Over the course of the days the aim is to test, document and better represent our selves in the bazaar store where things are already a little messy (slap wrists people). Through testing of packages we need to improve descriptions, icons and compliment the packages with screen shots to help our users.

=Day 1 - Wednesday 1st August 2012=

* Bazaar
** Package Improvement, Config, Dependancies, Documentation, Screenshot
*** Amazon S3
*** Green Spring
*** Batch Edit
*** Icon Builder

** Dependencies Ideas
** Bazaar Store Improvements - Seal of Approval, Screenshots, Tags, Display of Dependancies Field

* Core
** Loosing Data on Disable/Uninstall

===Green Spring===
* Capture screenshot

===Batch Edit===
* Installer fails to detect a lack of external dependencies: Spreadsheet::ParseExcel, Spreadsheet::WeiteExcel
* Install is a silent fail
* Uninstall fails with a misleading error ("Repository configuration not reloaded. Errors in configuration files" rather than not actually active)

===EXIF Import===
* Captured screenshots
* Plugin description could be a bit less brief
* Plugin does not actually work
* There is a dependancy on IMAGE::Exif
* once that is installed the plugin still fails
* Unhandled warning in Import::EXIF: File not found: *Fh::fh00001bear.jpg
* Warning Import failed: 1 item(s) imported before an error caused the import to abort.

===Icon Builder===
* Installs without issue
* must navigate to cgi/icon_builder (this should probably be a screen plugin with a link in key_tools or the admin panels)
* you can upload a jpg and modify the baground colour.
* when you hit export the file it returns is not a vaild jpeg

===AmazonS3===
* Installed
* updated package to do dependancy checking and output appropriate error messages
* outputs help to configure after installation
* created an example storeage policy
* tested fully
* dave t and dave m took screen shots

===OREExport===
* Installed plugin
* Took screen shots
* Export works
* Import works

===SNEEP===
* Installed
* works
* Screenshots

===Schedule===
* 11:30 - A Simple Start, take the easy packages and improve and screen shot them.
* 12:30 - Lunch
* 13:30 - Complex Bazaar Package Testing
The idea here is to test the more complex packages (those that require dependencies outside of those needed by eprints) and work out how to best support our "one click" users in installing these packages. Additionally we should looks for packages that need config and make sure they have a "config" link!. These packages include:
** Coversheets
** Preservation Toolkit
** Tweepository
** Open Office Toolkit

=Day 2 - Thursday 2nd August 2012=

* 09:30 - Bazaar Store Upgrades & Package Testing
Put all the stuff from yesterday in the store.
** Screenshots
** Dependencies
** Descriptions
** Icons
* 11:00 - Languages Packs
Take the language packs from files and put them in the store.
* 12:30 - Lunch
* 13:30 - Package Fest

=Day 3 - Friday 3rd August 2012=
* Package Fest

[[File:DSC_0020.JPG|thumb]]

=Attendees=

* Les Carr - University of Southampton
* David Tarrant - University of Southampton
* Tim Brody - University of Southampton
* Patrick McSweeney - University of Southampton
* Matthew Taylor - University of Southampton
* Adam Field - University of Southampton

Please add your name ...

* Ian Stuart - EDINA
* David McElroy - University of Glasgow
* Dawid Pachla - University of Glasgow
* Chris Yocum - EDINA

=Packages of Interest=

DON'T TOUCH: Shelves, Coverpage, REF, eNova, Kultivate