EPrints Documentation - User contributions [en-gb]

Views.pl

2024-07-02T16:45:18Z

Alan.stiles@open.ac.uk: /* Sections */ fixed typo

[[Category:Browse Views]]
{{dirs}}
{{cfgd}}

'''views.pl''' contains configuration for rendering ''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.
|- valign="top"
| max_items (V)
|Defaults to 2000. If the items list is larger increase the number enough to accomodate the number of items needed to be displayed.
max_items => 3000,
|}

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

Adding new views

2024-07-02T16:32:06Z

Alan.stiles@open.ac.uk: /* The basics */ fixed typo

[[Category:Manual]]
[[Category:Browse Views]]

Browse views provide a way for visitors to your site to discover relevant content without a specific item in mind (for example, browsing all the content associated with a particular topic). Visitors arriving directly at the page for a specific item in the repository (for example, via a search engine) also use views you have defined to discover related content.

There are two default views in EPrints - '''By Year''' and '''By Subject'''. This guide describes how to add additional views to your repository.
Instead with this link you can read a [http://wiki.eprints.org/w/Views.pl complete list of all options] avaible for views.

__TOC__

===The basics===

The views for your repository are defined in the views configuration file:

/opt/eprints3/archives/ARCHIVEID/cfg/cfg.d/views.pl

Open this file and find the browse_views configuration setting:

$c->{browse_views} = [
{
id => "year",
fields => "-date;res=year",
...
},
{
id => "subjects",
fields => "subjects",
...
},
];

The views are defined using a special (Perl) syntax: the view definition consists of a pair of curly braces (''note the comma after each closing brace'') enclosing a list of property/value pairs (note ''the comma'' after each line).

The key part of the view definition is the '''fields''' property. This names the metadata field (or fields) that EPrints will use to construct the view. For example, for the '''By Year''' view, EPrints groups the records in the repository according to their '''date''' (note that the '''res=year''' suffix tells EPrints to only consider the year part), and constructs a Web page for each date listing the records. Similarly, the '''Browse by Subjects''' view, groups the records according to the ''subjects'' they have been assigned to (a record may appear in more than one group!).

Both the '''Browse by Year''' and '''Browse by Subject''' views are constructed using the values of a single field ('''date''' and '''subjects''' respectively).

It is also possible to construct a view using the ''combined'' values of two or more fields (eg. group records by author '''and''' editor), or even using a sequence of two or more fields (eg. group records by journal title '''and then''' by volume number).

===Worked example: browse by organisational structure===

By default, EPrints has a ''divisions'' metadata field which allows authors to associate their deposits with the divisions (units, faculties, schools, departments, institutes, centres..) that were involved in producing their item (for example, the author's department, and the departments of any co-authors). This worked example allows visitors to browse the repository content by division.

Open the views configuration file:

/opt/eprints3/archives/ARCHIVEID/cfg/cfg.d/views.pl

Add the following definition to the browse_views setting:

$c->{browse_views} = [
{
id => "year",
...
},
{
id => "subjects",
...
},
{
id => "divisions",
fields => "divisions",
order => "-date/title",
hideempty => 1,
},
];

Save the file and generate the new view pages (this will also re-generate any existing views defined in the views configuration file):

bin/generate_views ARCHIVEID --verbose

Open the view page in a Web browser:

http://your.repository.url/view/

The view page lists all the available views. You should see your new views on the list:

[[Image:View_page2.png|frame|none|The view page lists available views]]

'''Fixing the undefined phrase warning''' The new view may appear on the views page with an ''undefined phrase'' warning (you may also notice a similar warning message when running generate_views):

["viewname_eprint_divisions" not defined]

Each view you create needs to be assigned a ''human-readable'' name, which EPrints will use on the view Web pages.

Edit the language-specific phrases file for view names:

/opt/eprints3/archives/ARCHIVEID/cfg/lang/en/phrases/views.xml

Add an appropriate phrase which describes the new view, for example:

<epp:phrase id="viewname_eprint_divisions">Division</epp:phrase>

Save the phrases file and regenerate the view pages:

bin/generate_views ARCHIVEID --verbose

===Example view definitions===

====Browse by type (3.3.8)====

Every deposit in EPrints has a type (article, book, thesis...). To allow visitors to browse your repository content by type, add the following definition to the browse_views setting:

{
id=>"doctype",
menus => [
{
fields => [ "type" ],
},],
order=>"-date",
},

====Browse by author====

===Example views (combined fields)===

====Browse by author and editor====

===Example views (multiple fields)===

====Browse by journal title, then by volume====

This example lets visitors browse the journals items in your repository have been published in, and then volumes within each journal.

{
id=>"journal_volume",
fields=>"publication,volume",
order=>"-date/title",
hideempty => 1,
},

[[Image:Browse_by_journal.png|border]]

[[Image:Browse_by_journal_volume.png|border]]

===Linking in your view===

You now need to add a link to your repository pages which takes visitors directly to your new view, or to the views page from where they can access all available views.

[[Image:Browse_by_navbar.png]]

====Generating CVs etc====

===Linking items back to views===
===Views as collections===

===New options in EPrints 3.1===

====subfield no longer supported====

The subfield option is no longer supported in EPrints 3.1.

====new_column_at====

This is an array of integers representing the number of items in a view list before another column is added. For example:

[ 10 ]

This would have one column of values until there were 11, then there would be 2 columns.

[ 10, 10 ]

This would have one column if there were ten or less values, two columns if there were between eleven and twenty (ten + ten) values, and three columns for all other cases.

[ 0, 0 ]

This would always have three columns.

Add one to the number of integers in the array and you get the maximum number of columns. The value of each integer defines the point at which that column becomes full, and more values cause an 'overflow' into the next column.

====variations====

This controls the various ways in which a browse view can be subheaded. It consists of a list of strings. Each string is the name of a non-compound metadata field (or the keyword DEFAULT, for an unsubheaded list), optionally followed by a semi-colon and a comma separated list of options. E.G:

variations => [
"creators_name;first_letter",
"type",
"DEFAULT"
],

See [[views.pl]] for the list of options.

Upgrading 3.3.12+ to 3.4

2023-09-14T14:22:49Z

Alan.stiles@open.ac.uk: /* Pre-upgrade */ clarified epm download source.

These instructions help you upgrade EPrints 3.3.16+ (or any newer version of EPrints 3.3) to EPrints 3.4 while keeping all your eprints, documents and local configuration changes.

It assumes your EPrints 3.3.16+ was installed using a tarball (tar.gz) file and installed in <code>/opt/eprints3</code>. The commands in these instructions assume Centos 7 OS and run as the eprints user, unless it is stated to run as the root user.

=Upgrade from Tarball=

==Pre-upgrade==
* If you have local modifications to the core files (in /opt/eprints3/perl_lib), you may need to manually migrate your changes.
* If you use Twitter integration, use CPAN to install LWP::Authen::OAuth as this is no longer in perl_lib. To do so, as root run:
cpan LWP::Authen::OAuth
* Download each of the Bazaar plugins you have installed as EPM files from your existing repository.
* Make a backup of your local configurations.

==Process==

We will move your existing eprints 3.3.16+ installation from <code>/opt/eprints3/</code> to <code>/opt/eprints3.3</code>, install eprints 3.4, then migrate your configurations into EPrints 3.4; cf. [https://wiki.eprints.org/w/Category:Installation Category Installation]
 
'''as root'''
apachectl stop
cd /opt
eprints3/bin/epindexer stop
mv eprints3 eprints3.3

* Download EPrints 3.4 core and publication flavour tarball and install them from [http://files.eprints.org/ Files.eprints.org] with
wget https://files.eprints.org/2551/7/eprints-3.4.3.tar.gz
wget https://files.eprints.org/2551/8/eprints-3.4.3-flavours.tar.gz
'''as root'''
cd /root
tar xvzf eprints-3.4.3.tar.gz
tar xvzf eprints-3.4.3-flavours.tar.gz

* Have a look to <code>/root/eprints-3.4.3/INSTALL</code> for some local adaption options.
'''as root'''
cd eprints-3.4.3
./configure
make install

* Move your current repository from 3.3 to 3.4
'''as root'''
cd /opt
mv eprints3.3/archives/ARCHIVENAME eprints3/archives/
* After moving, make sure all files inside <code>/opt/eprints3</code> are still owned by eprints user and belongs to eprints group, thus
'''as root'''
chown -R eprints:eprints /opt/eprints3

* Create <code>/opt/eprints3/archives/ARCHIVENAME/cfg/cfg.d/00_flavour.pl</code> to set the appropriate flavour, typically 'pub', i.e.
echo "\$c->{flavour} = 'pub';" > /opt/eprints3/archives/ARCHIVENAME/cfg/cfg.d/00_flavour.pl

* create a symbolic link to <tt>default.xml</tt>
cd /opt/eprints3/archives/ARCHIVENAME/cfg/templates/ (or /opt/eprints3/archives/ARCHIVENAME/cfg/lang/en/templates/
ln -s default.xml default_internal.xml

* Audit each of their local config files against the pub_lib flavours config files:
#The first <code>diff</code> below will identify all the files that are the same. If so, delete the ones in <code>archives/ARCHIVENAME/cfg/cfg.d/</code>. You almost certainly should not find any, as the files in <code>flavours/pub_lib/cfg.d</code> will at very least have updated copyright/licensing boilerplate.
#The second <code>diff</code> will find where files exists in both directory are different. Here they should be compared to see, if the local differences are superficial (e.g. slightly different comments or spacing) and therefore can be removed. Also the pub_lib flavour version may fix an outstanding bug or perform the required functionality more succinctly. If this is the only change, then the local archive version can be deleted, otherwise the change should be incorporated in the local version.
cd /opt/eprints3/
diff -rs archives/ARCHIVENAME/cfg/cfg.d flavours/pub_lib/cfg.d | egrep '^Files .+ and .+ are identical$'
diff -rq archives/ARCHIVENAME/cfg/cfg.d flavours/pub_lib/cfg.d | egrep '^Files .+ and .+ differ$'

<ul><li>Compare <code>archives/ARCHIVENAME/cfg/cfg.d/eprint_fields.pl</code> with <code>flavours/pub_lib/cfg/cfg.d/eprint_fields_pub.pl</code> maybe with the help of [http://diffuse.sourceforge.net/download_de.html ''diffuse''] to overcome this business easier:<ul>
<li>If these are different and fields are present in <code>eprint_fields_pub.pl</code> and not <code>eprint_fields.pl</code> or the definitions (e.g. type, options, etc.) for the same field are different then:<ol>
<li>Copy <code>flavours/pub_lib/cfg.d/eprint_fields_pub.pl</code> to their archive's <code>cfg/cfg.d/</code>.
<li>Modify the fields in their archive's <code>cfg/cfg.d/eprint_fields_pub.pl</code> where they have different definitions (e.g. type, options, etc.) to those in <code>eprint_fields.pl</code>.
<li>Remove all fields in their archive's <code>cfg/cfg.d/eprint_fields.pl</code> where they also occur in their archive's <code>cfg/cfg.d/eprint_fields_pub.pl</code>, no matter if already transferred due to previous item or initially the same.</ol>
<li>If there are only additional fields in <code>archives/ARCHIVENAME/cfg/cfg.d/eprint_fields.pl</code> then just do the last step.
<li>If the two files are identical then you need to do nothing. However, this is extremly unlikely.
</ul>
Finally, the specification is still the same, but mostly split into two distinct files, which obey the known rule ''Local version overrides central one''.</ul>
* Synchronise <code>archives/ARCHIVENAME/cfg/cfg.d/epm.pl</code> with <code>ingredients/bazaar/cfg.d/epm.pl</code>, i.e. remove <code>archives/ARCHIVENAME/cfg/cfg.d/epm.pl</code> in case of ''no'' local modifications.

* Ensure the following bazaar files are disabled by renaming to FILENAME.pl''.disabled''. Once they have been reinstalled via the Bazaar then they can be moved back into place. Using <code>epadmin test</code> is a good way of discovering which files need this doing, but below is a list of common files that should be temporarily moved, if they exist in your archive's <code>cfg/cfg.d/</code> directory:
mv z_orcid_support.pl z_orcid_support.pl.disabled
mv zz_hefce_oa_fields.pl zz_hefce_oa_fields.pl.disabled
mv zz_rioxx2.pl zz_rioxx2.pl.disabled
mv z_meprints.pl z_meprints.pl.disabled

* As the eprints user, run <code>epadmin update</code> to add any new fields that were not previously present (typically this is embargo_reason for documents and requester_email for request)
/opt/eprints3/bin/epadmin update ARCHIVENAME

* Generate new Apache configuration and as root test (fixing any issues) and restart Apache after necessary site-specific adaption are done.
/opt/eprints3/bin/generate_apacheconf --system --replace ARCHIVENAME
'''as root'''
apachectl configtest
apachectl restart

* Once confirming that EPrints is generally working. Go to Admin->Bazaar then install the Bazaar plugins you downloaded from your 3.3 repository before starting the upgrade process. This can be done by going to the Available tab in the Bazaar and strolling to the Upload section at the bottom. Unfortunately, you cannot do a bulk upload, so will need to install each plugin in turn.

* Move back the files you renamed to FILENAME''.disabled'' earlier, the epindexer into service and reload Apache
'''as root'''
/opt/eprints3/bin/epindexer start
apachectl graceful

* Finally, run <code>generate_static</code> to make sure all pages are regenerated with any changes to configuration.
/opt/eprints3/bin/generate_static ARCHIVEID

==Notes==
* 3.4 does not automatically update an archive's <code>html/en/</code> files. If there are any bugs with broken Javascript or unexpected CSS, try deleting the archives <code>html/en/javascript/auto.js</code> or <code>html/en/style/auto.css</code>. Similarly if a static page cannot be changed try deleting it under the archive's <code>html/en/</code> or running <code>generate_static</code>.
* If some perl modules are giving out error messages like:
Can't locate object method "new" via package "EPrints::Plugin::Event::PIRUS" at /opt/eprints3/bin/../perl_lib/EPrints/PluginFactory.pm line 276.
Can't locate object method "new" via package "EPrints::Plugin::Screen::EPrint::Box::Tools::SUPER" at /opt/eprints3/site_lib/plugins/EPrints/Plugin/Screen/EPrint/Box/Tools.pm line 12.
It is because their parent module has not been initialised. This happens when the parent module lives in perl_lib, and the problem module live in elsewhere; e.g. parent module of PIRUS(Event.pm) is in <code>./perl_lib</code>, while the <code>PIRUS.pm</code> is in <code>./pub_lib</code>.
Just need to <code>use</code> the parent module before the <code>ISA</code> line:
use EPrints::Plugin::Event;

[[Category:Upgrading]]

Installing EPrints on RHEL/Fedora/CentOS

2018-12-04T10:41:04Z

Alan.stiles@open.ac.uk: /* Installing from EPrints 3.3.x RPM */ Added note about proxy parameter to rpm calls

[[Category:Installation]]

==Requirements==

* RedHat Enterprise (RHEL) / CentOS 7 or Fedora 25+. These instructions will more than likely work for RHEL / CentOS 6 but have not been as thoroughly tested.

* Pre-installed MySQL server and client.
** RHEL / Fedora:
yum install mysql-server mysql
** CentOS:
yum install mariadb-server mariadb

== Installing from EPrints 3.3.x RPM ==

Add the rpm.eprints.org repository key:

rpm -ivh http://rpm.eprints.org/rpm-eprints-org-key-1-1.noarch.rpm

Next, add the rpm.eprints.org EPrints repository:

rpm -ivh http://rpm.eprints.org/eprints/noarch/rpm-eprints-org-1-1.noarch.rpm

Note: if these fail to connect to the repository and you have a proxy server, try adding the parameter "--httpproxy http://your.proxy.address" (export http_proxy doesn't affect rpm call)

Install required XML libraries (Use ''yum upgrade'' if these are already installed):

yum install libxml2 libxslt perl-XML-LibXML perl-XML-LibXSLT

Finally, install EPrints 3:

yum install eprints

=== Other Non-critical Dependencies ===
Some of EPrints non-core functionality may not work out of the box as these dependencies are not included as part of the RPM. Here is a list of known additional packages (and the YUM repositories in which they can be found) or CPAN modules than can be installed.

Some of these known additional packages are only available through the Extra Packages for Enterprise Linux (EPEL) YUM repository, which can be installed as the root user as follows:

yum -y install epel-release
yum repolist

CPAN modules should be installed using the ''cpan'' command as the root user.

* '''perl-Geo-IP (epel)''' - Allows IRstats2 to determine the location of views/downloads for publications.]
* '''perl-Spreadsheet-WriteExcel (epel)''' - To allow Multiline Excel export.
* '''CPAN module Text::Refer''' - Required for EndNote import.
* '''perl-Image-ExifTool (epel)''' - Sometimes needed to support generation of thumbnails for uploaded documents/images.
* '''perl-LWP-Protocol-https (base)''' - Needed by DataCite plugin to register repository DOIs.

== Installing EPrints 3.3.x from Source ==
'''N.B. Installing from source is generally discouraged particularly for production repositories. However, if want to develop the EPrints code or a plugin or Bazaar package it may be useful to install from source, ideally from [https://github.com/eprints/eprints EPrints Core Git repository].'''

First, install the EPEL YUM package repository and run yum repolist to ensure the GPG key is installed:

yum install epel-release
yum repolist

Now, install all the dependencies that would be installed through the eprints RPM.

yum install libxml2 libxslt httpd mod_perl perl-DBI perl-DBD-MySQL perl-IO-Socket-SSL perl-Time-HiRes perl-CGI \
perl-Digest-MD5 perl-Digest-SHA perl-XML-LibXML perl-XML-LibXSLT perl-XML-SAX perl-MIME-Lite tetex-latex wget \
gzip tar ImageMagick unzip elinks poppler-utils chkconfig

Next, create the eprints user

adduser eprints

Next, clone the Git repository from GitHub to /opt/ and set the eprints user as the owner. It is probably best to checkout the latest release rather than using HEAD, which may have known issues:

yum install git
git clone https://github.com/eprints/eprints.git /opt/eprints3
cd /opt/eprints3/
git checkout tags/v3.3.15
chown -R eprints:eprints .

Next, as the eprints user copy /opt/eprints3/perl_lib/EPrints/SystemSettings.pm.tmpl to /opt/eprints3/perl_lib/Eprints/SystemSettings.pm

EPrints is now fully installed at /opt/eprints3. However, you will not yet have a running archive. Follow the [[Getting Started with EPrints 3]] instructions to set this up.

Now update Apache configuration to set it up to use the eprints user and group, by ensuring the following lines are set thus in /etc/httpd/conf/httpd.conf:

User eprints
Group eprints

Now add the file /etc/httpd/conf.d/eprints.conf with the following line:

Include /opt/eprints3/cfg/apache.conf

There is a good chance your operating system will have SELinux enabled. If so, follow the instructions under Troubleshooting for how to let EPrints do what it needs to do through SELinux.

Finally, restart Apache:

service httpd restart

You should now be able to access your vanilla repository at the hostname you specified when running '''epadmin create''' from the [[Getting Started with EPrints 3]] instructions.

== Next steps ==

Configure eprints per [[Getting_Started_with_EPrints_3]].

== Troubleshooting ==

=== Starting database and webserver at boot ===
As with any database-backed web application, if you have not already done so you should ensure the database and webserver start up automatically after booting. For Redhat and Fedora use the following commands as root:

chkconfig httpd on
chkconfig mysqld on

For CentOS it will instead be:

chkconfig httpd on
chkconfig mariadb on

=== Failed to parse XML file ===
When installing EPrints on RHEL6 (may apply to other versions), If you get the error:
Failed to parse XML file:
/usr/share/eprints/lib/lang/en/phrases/system.xml: Entity: line 396: parser error : Entity 'nbsp' not defined age or title page. If there are more...

Run
sed -i 's/'''&'''nbsp;/ /g' /usr/share/eprints/lib/lang/en/phrases/system.xml

then navigate to the root of your EPrints install (/opt/eprints or /usr/share/eprints) and run
bin/generate_views *repository_id*
bin/epadmin reload *repository_id*

=== Upgrade from previous 3.3 ===
After a upgrading from previous 3.3, your existing repository's database may need updating.
bin/epadmin update [archive_id]

=== Apache in eprints group ===

If you choose not to run apache as the eprints user (for example you have another application on the same server) you will need to change https's groups and update the permissions on some directories

Add apache to eprints's group.
usermod apache -G eprints

One way to run httpd as 'apache' but still access eprints files is to add httpd to the eprints group.
chmod 770 /usr/share/eprints/var
chmod 770 /usr/share/eprints/lib/epm/

Be aware that other directories will need to be writable by eprints user group/apache ; those depend on whether you will be using eprints bazaar.

=== Using SELinux ===
If you're using SELinux on your server you will need to give Apache read/write access to the documents directory for all repositories you create and the eprints var folder (indexer log, ticker files):

chcon -R -h -t httpd_sys_script_rw_t [eprintspath]/archives/[repoid]/documents/
chcon -R -h -t httpd_sys_script_rw_t [eprintspath]/var/
chcon -R -h -t httpd_sys_script_rw_t /usr/share/eprints/lib/

You may also need to tell SELinux to allow Apache to talk on the network, if you intend to run your database on a separate server.

setsebool -P httpd_can_network_connect=1

=== Using firewalld ===
Typically RHEL/Fedora/CentOS run a firewall that will block remote connections to you webserver. To overcome this run the following commands as root:

firewall-cmd --permanent --add-service=http
service firewalld restart

You will need to same https if you intend to set that up as well. Otherwise, you can just disable the firewall altogether if you have an institutional level firewall:

service firewalld stop
chkconfig firewalld off

GDPR

2018-04-25T13:59:14Z

Alan.stiles@open.ac.uk: /* Non-Active Users Report */

This page has been created to gather information and share code snippets to help EPrints repositories handle GDPR responsibilities.

==Last Login Time==
Storing the last login time of a user can be useful to identify which users are active and which are not to help ensure data is not being stored longer than is necessary.

First a new user field for storing the time is required in user_fields.pl

<source lang="perl">
##user_fields.pl

push @{$c->{fields}->{user}},
{
'name' => 'last_login',
'type' => 'timestamp',
},
};
</source>

And then add the following code to $c->{check_user_password} in user_login.pl to store the time at which a user successfully logs in.

<source lang="perl">
##user_login.pl

#get user from username
my $user = EPrints::DataObj::User::user_with_username( $repository, $username );
return 0 unless $user;

#get time and compile a string
my( @local ) = localtime( time );
my ( $sec, $min, $hour, $day, $mon, $year ) = ( $local[0], $local[1], $local[2], $local[3], $local[4]+1, $local[5]+1900 );
my $loginTime = "$year-$mon-$day $hour:$min:$sec";

#store the value
$user->set_value( "last_login", $loginTime );
$user->commit();

#return user
return 1;

</source>

JLRS: An alternative approach (please discuss which is better) is to set the trigger on the loginticket dataset (different field spec from above - bigint):
<source lang="perl">
push @{$c->{fields}->{user}},
{
name=>"last_login",
type=>"bigint", #same as 'expires' field in EPrints::DataObj::LoginTicket
required=>0,
volatile=>1
}
;
$c->add_dataset_trigger( 'loginticket', EPrints::Const::EP_TRIGGER_CREATED, sub
{
my( %args ) = @_;
my( $repo, $loginticket ) = @args{qw( repository dataobj )};

# trigger is global - check that current repository 'user' dataset has last_login field to be updated
return unless $repo->get_dataset( "user" )->has_field( "last_login" );

#update volatile field in user record
my $user = EPrints::DataObj::User->new( $repo, $loginticket->get_value( "userid" ) );
if( defined $user ){
$user->set_value( "last_login", $loginticket->get_value( "expires" ) );
$user->commit();
}
}, priority => 100 );
</source>

==Non-Active Users Report==
TODO
worth having a count of items linked with the user on the report, along with their statuses?

==Delete User Action==
*Suggestion* Cron job to select all user accounts which have been inactive over a certain time threshold, check those users for affiliation to a publication (creator, editor, depositor etc.) which is either archive or buffer status and, where no connection exists, remove those user accounts.

Admin will be able to select user accounts from the report to delete (within the report or individually?)

==Add 'Agree to privacy and data statement' checkbox on registration or request forms==
TODO - should be 'versioned' - so if the statement changes, the version that was agreed to can be shown.
Possibly a set/namedset, with the available options limited to only one when rendered to a user?

GDPR

2018-04-25T13:58:59Z

Alan.stiles@open.ac.uk: /* Delete User Action */

This page has been created to gather information and share code snippets to help EPrints repositories handle GDPR responsibilities.

==Last Login Time==
Storing the last login time of a user can be useful to identify which users are active and which are not to help ensure data is not being stored longer than is necessary.

First a new user field for storing the time is required in user_fields.pl

<source lang="perl">
##user_fields.pl

push @{$c->{fields}->{user}},
{
'name' => 'last_login',
'type' => 'timestamp',
},
};
</source>

And then add the following code to $c->{check_user_password} in user_login.pl to store the time at which a user successfully logs in.

<source lang="perl">
##user_login.pl

#get user from username
my $user = EPrints::DataObj::User::user_with_username( $repository, $username );
return 0 unless $user;

#get time and compile a string
my( @local ) = localtime( time );
my ( $sec, $min, $hour, $day, $mon, $year ) = ( $local[0], $local[1], $local[2], $local[3], $local[4]+1, $local[5]+1900 );
my $loginTime = "$year-$mon-$day $hour:$min:$sec";

#store the value
$user->set_value( "last_login", $loginTime );
$user->commit();

#return user
return 1;

</source>

JLRS: An alternative approach (please discuss which is better) is to set the trigger on the loginticket dataset (different field spec from above - bigint):
<source lang="perl">
push @{$c->{fields}->{user}},
{
name=>"last_login",
type=>"bigint", #same as 'expires' field in EPrints::DataObj::LoginTicket
required=>0,
volatile=>1
}
;
$c->add_dataset_trigger( 'loginticket', EPrints::Const::EP_TRIGGER_CREATED, sub
{
my( %args ) = @_;
my( $repo, $loginticket ) = @args{qw( repository dataobj )};

# trigger is global - check that current repository 'user' dataset has last_login field to be updated
return unless $repo->get_dataset( "user" )->has_field( "last_login" );

#update volatile field in user record
my $user = EPrints::DataObj::User->new( $repo, $loginticket->get_value( "userid" ) );
if( defined $user ){
$user->set_value( "last_login", $loginticket->get_value( "expires" ) );
$user->commit();
}
}, priority => 100 );
</source>

==Non-Active Users Report==
TODO

==Delete User Action==
*Suggestion* Cron job to select all user accounts which have been inactive over a certain time threshold, check those users for affiliation to a publication (creator, editor, depositor etc.) which is either archive or buffer status and, where no connection exists, remove those user accounts.

Admin will be able to select user accounts from the report to delete (within the report or individually?)

==Add 'Agree to privacy and data statement' checkbox on registration or request forms==
TODO - should be 'versioned' - so if the statement changes, the version that was agreed to can be shown.
Possibly a set/namedset, with the available options limited to only one when rendered to a user?

Talk:GDPR

2018-04-25T13:28:49Z

Alan.stiles@open.ac.uk:

I'm kind of torn between the two methods - John's has the advantage that it isn't dependent upon the mechanism by which someone creates a login ticket so should be more universal (e.g. for us), but Will's has the advantage that it's perhaps easier to understand for the less specialist eprints dev / admin. I.e. it doesn't use the magic of triggers, and it uses a date format that can be easily read rather than epoch timestamp (which apparently not everyone tracks on a daily basis) - Alan (2018-04-25 14:12:30z+01:00)

== Code queries ==

John, Are you deliberately storing just the expiry date of the login ticket rather than the specific login time? Grand scheme I don't suppose it makes a lot of difference if there's an extra 7 days in the delete check. - Alan

Talk:GDPR

2018-04-25T13:28:27Z

Alan.stiles@open.ac.uk: /* Code queries */ new section

Talk:GDPR

2018-04-25T13:12:58Z

Alan.stiles@open.ac.uk:

Talk:GDPR

2018-04-25T13:12:05Z

Alan.stiles@open.ac.uk: Created page with "I'm kind of torn between the two methods - John's has the advantage that it isn't dependent upon the mechanism by which someone creates a login ticket so should be more univer..."

Id field

2016-12-19T14:45:01Z

Alan.stiles@open.ac.uk: updated description around deprecation

{{fieldtypes}}

[[Metadata]] field.

Was marked as 'Deprecated. This is a lingering part of EPrints 2 and should not be used' but has continued to be used through 3.3.x versions and as the basis of new Identifier types e.g. ORCID.
Useful in search as a 'match full value' rather than partial match of e.g. type 'text'

Category:EPrints Metadata Fields

2016-12-19T14:42:48Z

Alan.stiles@open.ac.uk: /* Internal-use and Deprecated Field Types */ removed deprecation from ID field

[[Category:EPrints 3 Reference]]
{{fieldtypes}}
== Metadata Field Types ==

There are many different types of metadata field. The type controls how a field is rendered, indexed, searched and so forth. A field always has a type and a name property, and usually has several more. Most properties are documented on this page, but some properties are only available to certain types of field, and they are listed on the page for that field.

Some of these subclasses provide very rich features, others very simple. For example the [[url field]] works just like the text field except that it's only valid if it looks like a url and when rendered it is a hyper-link.

A metadata field describes one field of data in one type of [[Data Object]]. For example the "title" field of an [[EPrint Object]] or the "email" field in a [[User Object]].

Every [[Data Object]] has system fields (which are set by the system, and not alterable), but the [[User Object]] and [[EPrint Object]] have additional fields which are configured on a per-repository basis.

These can be customised in the [[user_fields.pl]] and [[eprint_fields.pl]] files. Note that changing these files does not automatically modify the underlying database so should (generally) only be done before the database is created. Some metadata properties do not affect the database, and are marked as such.

If you add or remove fields, or modify a property which affects the database then you'll need to alter the database to match. In 3.0 this must be done by hand, but we have plans to build a tool to do this for you.

Default values marked *config indicate that the default value for the repository may be modified in the configuration file [[field_property_defaults.pl]]

== Inheritance ==

This is the list of ''useful'' field types. Under it is listed the other field types which are just included for completeness and are not intended to be used as part of the configuration.

Some field types inherit the properties of another, and then modify them in some way. For example the [[namedset field]] works like a [[set field]] except that it gets its options from a namedsets file not from the options=>[] in the field properties.

* '''Basic metadata field''' - this is abstract, fields must be one of the types listed below...
** '''[[Boolean field|Boolean]]''' - TRUE or FALSE (or can be unset, of course)
** '''[[Compound field|Compound]]''' - virtual field, joins together several "multiple" fields, e.g. author_name and author_email
*** '''[[Multilang field|Multilang]]''' - allows language variants of a field, e.g. titles in French, German and/or English.
** '''[[Date field|Date]]''' - stores a date
*** '''[[Time field|Time]]''' - stores a date and time
** '''[[Float field|Float]]''' - stores a floating-point value
** '''[[Int field|Int]]''' - a positive integer value
*** '''[[Itemref field|Itemref]]''' - a reference to another [[Data Object]] (e.g. a user or other eprint)
*** '''[[Pagerange field|Pagerange]]''' - a pagerange, e.g. 122-130
** '''[[Search field|Search]]''' - a serialised search
** '''[[Set field|Set]]''' - a limited set of options
*** '''[[Namedset field|Namedset]]''' - like a normal set, but takes its options from a [[namedset]] configuration file.
*** '''[[Subject field|Subject]]''' - possible values are taken from the [[Subject]] heirarchy.
** '''[[Text field|Text]]''' - the basic text field. Maximum 255 bytes. nb. uft-8 means some chars take more than one byte.
*** '''[[Email field|Email]]''' - an email address
*** '''[[Longtext field|Longtext]]''' - like text but allows much longer text (65,000 bytes)
*** '''[[Name field|Name]]''' - Stores a person's name broken up into logical parts.
*** '''[[Url field|Url]]''' - stores a URL

=== Internal-use and Deprecated Field Types ===

* '''Basic metadata field'''
** '''[[File field|File]]''' - virtual field represtenting the files in a document
** '''[[Id field|Id]]'''
** '''Int'''
*** '''[[Year field|Year]]''' - deprecated (do not use)
** '''[[Search field|Search]]''' - a serialised search
** '''Set'''
*** '''[[Arclanguage field|Arclanguage]]''' - as for set, but the options are the valid languages of this repository
*** '''[[Fields field|Fields]]''' - as for set, but the options are the fields in a dataset.
*** '''[[Langid field|Langid]]''' - used internally by [[multilang field]]s to store the language id.
** '''[[Subobject field|Subobject]]''' - a virtual field, similar to itemref, but representing an object or objects which are sub-parts of the current object (as oppose to just related in some way)
** '''Text'''
*** '''[[Fulltext field|Fulltext]]''' - virtual field used to represent the full text of an eprint
*** '''[[Secret field|Secret]]''' - used to store passwords

== Properties ==

Note that true/false properties use 1 and 0 to indicate their setting.

Some properties can be temporarily set or overridden by the [[Workflow Format]] and [[Citation Format]] files.

=== Core Properties ===

{| cellpadding="3" cellspacing="0" border="1"
| name || default || description
|-
| '''name''' || n/a || '''This property is always required (except on sub-fields of compound fields). This property affects the database structure.''' This is the internal name of the field. It should only contain a-z and underscores. It will be used to identify this field in scripts, other configuration files, in the database, and in the XML export/import system, etc. It must be unique within the object (so the [[EPrint Object]] can't have two fields called "email" but the eprint object and [[User Object]] could have a field each of the same name.
|-
| '''type''' || n/a || '''This property is always required. This property affects the database structure.''' This sets the type of the metafield, which in turn affects what other properties it may have. The value must be one of the metafield types listed above.
|-
| '''multiple''' || 0 || '''This property affects the database structure.''' This indicates if this field is a single value or a list of values. eg. "title" is only a single [[longtext field]] but "creators" is a multiple [[name field]]. In the database a non-multiple field is stored in one (or more) columns in the main object table, but a multiple field gets its own table.
|-
| '''sql_index''' || 1 || When the database is created this field indicates that an SQL index should be created to speed searching. Different field types override the default value with the sensible option for that type of field. It's not worth putting an sql index on a field that is only ever searched for words in it (like title or abstract) but it is worth indexing fields whoes values are explicitly searched for, or where ranges are searched - date fields, set fields etc. It's unlikely you'll need to set this by hand. You could change it after the database has been created; it won't break anything. In fact, it won't do anything at all.
|-
| '''sub_name''' || undef || '''This property affects the database structure.''' This is a special property which is required INSTEAD of the name field for the sub fields inside compound fields. The actual name of these fields is then forced to be parent field name+"_"+sub_name. For example in compound field "creators" is a sub field with sub_name "name". In this case the actual name of the name field in the system, database etc. is creators_name.
|}

=== Rendering Properties ===

These properties affect how values of the metadata in this field are rendered.

Certain of these properties can be turned on temporarily by the [[Citation Format]] files - render_magicstop for example.

{| cellpadding="3" cellspacing="0" border="1"
| name || default || description
|-
| '''browse_link''' || undef || This is the name of a [[view]] which values of this field should be linked to. For example if their was a browse by publishers view configured named "pubs", then adding browse_link=>"pubs" to the publisher field would cause it to be linked into the page for the named publisher whenever it is rendered.
|-
| '''render_quiet''' || 0 || Normally if a field is rendered an it isn't set, it is rendered as a big ugly "UNSPECIFIED". Setting render_quiet on a field means it just gets rendered as nothing if it's empty.
|-
| '''render_magicstop''' || 0 || If true then this renders a full stop at the end of this field. Unless the last character is a dot, question mark or exclamation mark. This helps avoid the ugly "World without Cheese?." affect you get when titles end in ? or !.
|-
| '''render_noreturn''' || 0 || If true then all CR and LF's are turned into normal spaces.
|-
| '''render_dont_link''' || 0 || Set this to true to stop this field hyperlinking itself when rendered. Currently only affects [[url field]]s and [[email field]]s.
|-
| '''render_single_value''' || undef || The value of this property is the name of a subroutine to call to render values from this field. For a multiple field this is called once per value in the list of values. The function should take the following parameters: ( $session, $field, $value, $object). It should return an [[XHTML DOM]] object of the rendered value.
|-
| '''render_value''' || undef || As with render single value, but this gets passed the entire list of values (an array reference) if it's a multiple field. Parameters passed are: ( $session, $self, $value, $all_langs, $no_link, $object ). $all_langs indicates that all language variants should be shown - only really useful for multilang fields. $no_link being true is a request to place no hyperlinks in the resulting HTML. It should return an [[XHTML DOM]] object of the rendered value.
|}

=== Input and Validation Properties ===

{| cellpadding="3" cellspacing="0" border="1"
| name || default || description
|-
| '''required''' || 0 || If this is set to true then the field is always marked as required, no matter what the workflow says.
|-
| '''input_add_boxes''' || 2 *config || The number of rows to add when clicking the "more rows" button in a multiple or multilang field.
|-
| '''input_boxes''' || 3 *config || The number of input rows to initially show in a multiple field.
|-
| '''input_cols''' || 60 *config || The number of columns in a text input field.
|-
| '''input_rows''' || 10 *config || For longtext input fields, the number of rows of input to show. For set fields this is the number of items to show in a select menu.
|-
| '''input_lookup_url''' || undef || The URL to use for autocompletion. This is generally set using the workflow configuration rather than directly in the field configuration. The URL must be on the same server hostname as the repository.
|-
| '''input_lookup_params''' || undef || Additional parameters to pass to the input_lookup_url. For example an indication of which autocomplete file to use.
|-
| '''input_ordered''' || 1 || This is true by default. In some multiple fields, such as creators, the order of the values is important and by default numbers are shown to the left of input rows and to the right are "move up" and "move down" arrows. However, with some multiple fields the order is not important in which case you can set this to zero to stop the arrows and numbers being shown.
|-
| '''render_input''' || undef || The name of a subroutine which will render the input for this field. This is a bit tricky to use as it must return the same CGI parameters as the default input form would have. It's easiest on simple fields. The subroutine is passed the following parameters ( $field, $session, $current_value, $dataset, $staff, $hidden_fields, $object, $basename ). It should return the [[XHTML DOM]] object of the chunk of HTML form.
|-
| '''maxlength''' || 255 || This is a limit to the maximum allowed size of a value. It may be useful, for example, as a very simple validation check. Also it may confuse users to be allowed to type in 255 characters in a "postcode/zipcode" field.
|-
| '''toform''' || undef || This function is allowed to modify the current value which appears in the form. For example, if your database stores userids in a field, but you want to allow people to edit them as usernames, then this function can be used to take the current value (a userid) and return the associated username. This value is what appears in the field in the search form. It is passed ( $value, $session, $object, $basename ) and returns the user-facing version of $value. **As of version 3.3.13 this only gets passed $value and $session in Metafield.pm**
|-
| '''fromform''' || undef || The inverse of toform. This takes the value from the form and converts it into the value that will be stored in the database. It is passed the parameters ( $value, $session) when $value is the value entered on the web form, and the return value is the value to be stored in the database. This function is not called when editing the eprint is cancelled.
|-
| '''help_xhtml''' || undef || This can only be set via the [[Workflow Format]] configuration not via the metadata field directly. It is used to contain the XHTML to use as the help for this field. This is so that the workflow can conditionally change the help on a field.
|}

=== Ordering, Indexing and Searching ===

{| cellpadding="3" cellspacing="0" border="1"
| name || default || description
|-
| '''text_index''' || 0 || If set to true the the indexer considers this field for full text indexing. Otherwise not. Some types of metadata field have a default of true, for example text and longtext.
|-
| '''search_cols''' || 40 *config || How many columns (characters) wide the input field for searching this type of field. If one search field searches more than one field then the properties from the first listed field are used.
|-
| '''make_single_value_orderkey''' || undef || The orderkey is the (potentially language specific) string used to order by this field. This property allows you to define a method to override the default eprints orderkey generation. This property is passed each value from multiple fields, in turn. It is passed ($field, $value) and returns an ordervalue string.
|-
| '''make_value_orderkey''' || undef || As with make_single_value_orderkey but this is passed the array reference for a multiple field rather than just single values. It should return the orderkey string for the entire value. It is passed ( $field, $value, $session, $language_id ).
|}

=== Other Properties ===

{| cellpadding="3" cellspacing="0" border="1"
| name || default || description
|-
| '''can_clone''' || 1 || If this is set to false then this field is not copied when the object is
cloned. This is mostly used by system fields such as "dir" or "datestamp".
|-
| '''show_in_fieldlist''' || 1 || Set this to false to prevent this field appearing in [[fields field]] lists. This is primarily to allow you to remove it from the list of fields in the user configuration which are used to control which fields appear as columns in the Items and Review screens.
|-
| '''show_in_html''' || 1 || If set to false then this field is not shown in the Details tab of the eprint control page. This is mostly used to hide confusing internal system fields like "dir".
|-
| '''export_as_xml''' || 1 || Set this to false to prevent the field being exported in the XML export. This is handy to supress either confidential or confusing fields, like the fileinfo system field.
|-
| '''import''' || 1 || If set to false then new eprints can't be created with this value. For example "eprintid", "dir" and so forth have this set to false. This can also prevent fields being set when import tools are used.
|}

=== Internal Properties ===

These are set by the system. Editing them by hand will do '''''strange things'''''.

{| cellpadding="3" cellspacing="0" border="1"
| name || default || description
|-
| '''parent_name''' || undef || On subfields of compound fields this is set automatically to be the name of the parent field.
|-
| '''confid''' || *special || This is set to the id of the dataset that this field belongs to and is used to work out what phrase ids etc. it uses.
|}

=== Deprecated or Buggy Properties ===

Don't use these!

{| cellpadding="3" cellspacing="0" border="1"
| name || default || description
|-
| '''input_advice_right''' || undef || Do not use.
|-
| '''input_advice_right''' || undef || Do not use.
|-
| '''input_assist''' || undef || Do not use.
|-
| '''requiredlangs''' || [] || Do not use.
|-
| '''allow_null''' || 0 || Do not use. Planned for use with compound fields, but not implemented in 3.0.
|}

== Required Phrases ==

These are phrases which you need to define in the local repository phrases file to control how this field renders. Some types of field (eg. [[set field]]s) have additional phrases in addition to the ones listed below.

The actual name of the field, as it will appear to users is stored in

datasetid + "_fieldname_" + fieldname

The default help to display, when the field is being input, is stored in

datasetid + "_fieldhelp_" + fieldname

For example:

<epp:phrase id="eprint_fieldname_abstract">Abstract</epp:phrase>
<epp:phrase id="eprint_fieldhelp_abstract">A summary of the items content.
If the item has a formal abstract then that is what should be entered
here. No complicated text formatting is possible.</epp:phrase>

== Database ==

Most fields have a representation in the SQL database using one or more columns. The sub-pages for each field type give the details.

== API ==

When you request (or set) a value of a metadata field, it is usually handled as a perl scalar (which is a string or number).

ALL values passed around in the API should be encoded in utf-8 or BAD THINGS may happen.

For example,

$eprint->set_value( "title", "For Us, The Living" );

Sets the title to the given string.

my $foo = $eprint->get_value( "title" );

Sets $foo to the string of the title, eg. "For Us, The Living".

=== Multiple Fields ===

If a field is set to multiple, then instead of a single value, a reference to an array of values is used. Eg.

$eprint->set_value( "corp_creators", [ "Jims Research", "Jones Research ] );

=== Other Exceptions ===

See the specific page for the full details.

* [[name field]]s are represented as a hash of the parts.

* [[compound field]]s do something a bit clever.

ORCID

2016-10-27T14:16:40Z

Alan.stiles@open.ac.uk: /* Eprints Contributors (e.g. creators, editors) */ capital 'O'

This page has been created to gather information about how different EPrints repositories have integrated ORCID.
At this time (April 2016) there doesn't seem to be a 'best practice' approach that has been adopted widely - this will hopefully change over time.

==Field Recommendations==
As at 2016-10-18 these are the recommended field names and types as discussed at the Jisc ORCID hack day in London - Alan Stiles, John Salter, Adam Vials Moore, Peter West, Andrew Beeken

===New MetaField Type===
* Type 'Orcid' is a subtype of 'id', provides validation and render methods
N.B. Store the 16 digit, hyphen separated value, without the authority (host) details e.g. 'nnnn-nnnn-nnnn-nnnn' (as per the value returned by the ORCID API)

===User Object===
*new field named 'orcid', type 'Orcid' to store the value of the ORCID id for that user

====Suggested fields====
*'orcid_auth_code', type text - to hold the long authorisation token returned by the ORCID API at the end of a successful OAuth2 process
*'orcid_granted_permissions', type text - to hold the permissions granted via the ORCID API during the authorisation process
*'orcid_token_expires', type time - to hold the expiry timestamp for the authorisation code above (time now plus expires duration returned by the ORCID API)
*'orcid_last_update_timestamp', type text - to hold the timestamp of the last time the user's ORCID record was processed, to enable quicker reprocessing in the future.
*'orcid_webhook_ref', type text - to hold the value provided when configuring the webhook notification to validate new notifications have come from ORCID

Also potential fields for requested permissions .e.g. boolean flags or text to capture auth codes if individual permissions captured separately? (e.g. Peter West work)

===Eprints Contributors (e.g. creators, editors)===
*new sub-field of contributor_orcid (e.g. creator_orcid, editor_orcid) type 'Orcid' to store the value of the ORCID id for that contributor

==Previous Discussions==
If you are looking to retrieve publications from the ORCID service, the [http://bazaar.eprints.org/354/ Import from ORCID (Tier 1 API)] Bazaar package, or the [https://github.com/eprintsug/orcidt2 ORCID Tier 2 api framework] are good places to start.

2016-05-20 [[User:Alan.stiles@open.ac.uk|Alan Stiles]] at The Open University is working on a plugin to connect EPrints with ORCID via the Tier 2 Members API to retrieve ORCID ids and synchronise publications and affiliation details.

Some aspects that need to be considered when adopting ORCIDs, and making them available to other systems are:

* storing the ORCID (see: http://support.orcid.org/knowledgebase/articles/116780-structure-of-the-orcid-identifier)
* rendering the ORCID in abstract pages (see [http://support.orcid.org/knowledgebase/articles/116780-structure-of-the-orcid-identifier link above])
* exposing ORCIDs over OAI-PMH metadata profiles e.g. RIOXX

NB The examples below may refer to the 'creators' field - but the same approach could be used to extend other 'person' fields - e.g. contributors.

= Re-using creators.id subfield =

The creators.id field is labelled 'email' by default, but as it's an 'id' type field, it can be used to store ORCIDs.
To re-label the field, a simple addition to a phrase file in <code>archives/ARCHIVEID/cfg/lang/en/phrases/</code> needs to be made:
<source lang="xml">
<epp:phrase id="eprint_fieldname_creators_id">ORCID / Creators email (if known)</epp:phrase>
</source>

== Rendering the ORCID in a citation ==
The rendering of this field then needs to be changed to accommodate an author with an ORCID. The following script adds methods that can be called via the EPScript language:

<source lang="perl">
# add to e.g. ~/archives/ARCHIVEID/cfg/cfg.d/z_add_to_EPrints_Script_Compiled.pl
# Write into EPrints::Script::Compiled package to allow use of function in epscript
{
package EPrints::Script::Compiled;
use strict;

sub run_wrro_people_with_orcids
{
my( $self, $state, $value ) = @_;

my $session = $state->{session};
my $r = $state->{session}->make_doc_fragment;

my $creators = $value->[0];

foreach my $i (0..$#$creators){

my $creator = @$creators[$i];

if( $i > 0 ){
#not first item (or only one item)
if( $i == $#$creators ){
#last item
$r->appendChild( $session->make_text( " and " ) );
} else {
$r->appendChild( $session->make_text( ", " ) );
}
}

my $person_span = $session->make_element( "span", "class" => "person" );
$person_span->appendChild( $session->render_name( $creator->{name} ) );

my $id = $creator->{id};
if( defined $id && $id =~ m/^(?:orcid.org\/)?(\d{4}\-\d{4}\-\d{4}\-\d{3}(?:\d|X))$/ )
{
my $orcid_span = $session->make_element( "span", "class" => "orcid" );

# According to https://orcid.org/trademark-and-id-display-guidelines
# "recommended display is a hyperlinked URI preceded by the iD icon"
# This looks terrible in a citation. Removed for the time being.
#
# my $orcid_link = $session->make_element(
# "a",
# "href" => "http://orcid.org/",
# "target" => "_blank",
# "class" => "orcid-icon"
# );
# $orcid_link->appendChild( $session->make_element(
# "img",
# "src" => "/images/orcid_16x16.png",
# "title" => "ORCID"
# ) );
# $orcid_span->appendChild( $orcid_link );

my $link = $session->make_element(
"a",
"href" => "http://orcid.org/$1",
"target" => "_blank",
);
$link->appendChild( $session->make_text( "orcid.org/$1" ) );

$orcid_span->appendChild( $session->make_text( "(" ) );
$orcid_span->appendChild( $link );
$orcid_span->appendChild( $session->make_text( ")" ) );

$person_span->appendChild( $session->make_text( " " ) );
$person_span->appendChild( $orcid_span );
}
$r->appendChild( $person_span );
}

return [ $r, "XHTML" ];
}

}
# END EPrints::Script::Compiled additions
</source>

You may also want a bit of CSS to style ORCID links
<source lang="css">
/* Add to e.g. ~/archives/ARCHIVEID/cfg/static/style/auto/zzz_orcid.css */
.person:hover {border-bottom: 1px dashed #a6ce39;}
.orcid {}
.orcid a:hover {
color: #a6ce39;
}
.orcid-icon {}
.orcid-icon img { vertical-align: text-bottom; margin: 0 4px 0 2px; }
</source>

And finally, you have to call the new EPScript function from a citation file e.g. <code>archives/ARCHIVEID/cfg/citations/eprint/default.xml</code>
<source lang="xml">

<print expr="wrro_people_with_orcids(creators)" />
</source>

== Exposing the ORCID in RIOXX ==
Based on re-using the creators.id field, this block of code over-writes the default <code>rioxx2_value_author</code> function.
<source lang="perl">
# Add to e.g. ~/archives/ARCHIVEID/cfg/cfg.d/zzz_rioxx2_overwrites.pl
$c->{rioxx2_value_author} = sub {
my( $eprint ) = @_;

my @authors;
for( @{ $eprint->value( "creators" ) } )
{
my $id = $_->{id}; # if you use a custom 'orcid' field, reference that here instead of 'id'
if( defined $id && $id =~ m/^(?:orcid.org\/)?(\d{4}\-\d{4}\-\d{4}\-\d{3}(?:\d|X))$/ )
{
push @authors, {
author => EPrints::Utils::make_name_string( $_->{name} ),
id => "http://orcid.org/$1"
};
} else {
push @authors, {
author => EPrints::Utils::make_name_string( $_->{name} ),
};
}
}

#NB If your corp_creators has DOIs or ISNIs for the entries, a similar method could be used to include these here.
foreach my $corp ( @{ $eprint->value( "corp_creators" ) } )
{
my $entry = {};
$entry->{name} = $corp;
push @authors, { author => $corp };
}

return \@authors;
};

</source>

= Add additional identifiers to creators =
Another approach to storing ORCIDs is to add an additional sub-field to the creator field.
This has been discussed on the Eprints tech list. If you know how to do this, please document it here!

This is how University of Bath has done it. We're getting the ORCID data from another system, so have used a text field to capture it for display. At present there is no special rendering on it, it's just displaying as a number.
<source lang="perl">
{
name => 'creators',
type => 'compound',
multiple => 1,
fields => [
{
sub_name => 'name',
type => 'name',
hide_honourific => 1,
hide_lineage => 1,
family_first => 1,
},
{
sub_name => 'id',
type => 'text',
input_cols => 20,
allow_null => 1,
},
{
sub_name => 'orcid',
type => 'text',
input_cols => 20,
allow_null => 1,
}

],
input_boxes => 4,
},
</source>
This is how University of Pittsburgh has done it:
<source lang="perl">
{
'name' => 'creators',
'type' => 'compound',
'multiple' => 1,
'fields' => [
{
'sub_name' => 'name',
'type' => 'name',
'hide_honourific' => 1,
'hide_lineage' => 1,
'family_first' => 1,
},
{
'sub_name' => 'email',
'type' => 'text',
'input_cols' => 20,
'allow_null' => 1,
},
{
'sub_name' => 'id',
'type' => 'text',
'input_cols' => 20,
'allow_null' => 1,
},
{
'sub_name' => 'orcid',
'type' => 'id',
'input_cols' => 19,
'allow_null' => 1,
},
],
'input_boxes' => 4,
'render_value' => 'custom_render_creators_with_orcid',
},

</source>

==Notes from Pittsburgh:==
(Information courtesy of Brian Gregg - bdgregg@pitt.edu)

We have added some ORCID functionality in our IR System here at the University of Pittsburgh. We however have not “linked” our IR with orcid.org in anyway such as we do not have a lookup user in ORCID or the ability to add publications from ORCID to our IR. The only link is the entering of the ORCID into the system so that it can be displayed.

An example record is available here: [http://d-scholarship.pitt.edu/28114/ http://d-scholarship.pitt.edu/28114/]

# Users have an ORCID field in their profile – user_fields.pl
# Any “Creator” types have an ORCID field added to the workflow – eprint_fields.pl
# We have added ORCID validation adhering to this document: [http://support.orcid.org/knowledgebase/articles/116780-structure-of-the-orcid-identifier] - eprint_validate.pl
# We have added the ORCID to the “lookup” function to populate the ORCID field from any user entries in the database. – cgi/users/lookup/name
# We display the ORCID as such on the input form, where the green icon links out to our own orcid.pitt.edu site, but could be to orcid.org by default.
# We display the ORCID as such on the public display of the record where the ORCID is linked out to orcid.org (see [http://d-scholarship.pitt.edu/28114/ example record])

ORCID Validator - snippet for eprints_validate.pl
<source lang="perl">
# ORCID ID Validator for individuals
# Reference: http://support.orcid.org/knowledgebase/articles/116780-structure-of-the-orcid-identifier
# REGEX: ^\d{4}-\d{4}-\d{4}-(\d{3}X|\d{4})$
#
my @name_fields = qw( creators contributors exhibitors producers conductors lyricists ); #which ever name fields you added 'orcid' to.
foreach my $name_field ( @name_fields )
{
if( $eprint->is_set( $name_field ) )
{
foreach my $creator ( @{ $eprint->value( $name_field ) } )
{
my $orcid = $creator->{orcid};
next unless defined $orcid;
if ($repository->get_repository->can_call ( "validators", "isValidORCID" ) )
{
if (!$repository->get_repository->call( [ "validators", "isValidORCID" ], $orcid ))
{
my $field_text = $repository->html_phrase( "eprint_fieldname_$name_field" );
my $field_frag = $repository->make_element( "span", class=>"ep_problem_field:$name_field" );
$field_frag->appendChild($field_text);
push @problems, $repository->html_phrase( "warnings:orcid_invalid",
orcid => $repository->get_repository->make_text($orcid),
field => $field_frag,
);
}
} else {
$repository->get_repository->log( "Can not call isValidORCID." );
}
}
}
}
</source>

Phrase for "warnings:orcid_invalid":

<source lang="xml">
<epp:phrase id="warnings:orcid_invalid">The ORCID ID: <epc:pin name="orcid"/> is not a valid ORCID ID as it does not conform to the ORCID ID specification. Please edit the <epc:pin name="field"/> with the associated ORCID or remove it from the name completely.</epp:phrase>
</source>

Additional Function that can be placed either at the end of eprints_validate.pl (after the final };) or elsewhere:
<source lang="perl">
############################################
# Function: isValidORCID
# Description: Used to validate ORCID IDs
#
# From: http://support.orcid.org/knowledgebase/articles/116780-structure-of-the-orcid-identifier (Checksum)
#
$c->{validators}->{isValidORCID} = sub {
my $ORCID = $_[0];
#Check for valid length of 19 characters.
my $size = length($ORCID);
if ($size > 19 )
{
return 0;
} else {
#Check actual validity of the ID mathematically.
$ORCID =~ s/\-//g;
my @chars = split(//, $ORCID);
my $total = 0;
for ( my $i=0; $i<15; $i++) {
$total = ($total + $chars[$i]) *2;
}
my $remainder = $total % 11;
my $result = (12 - $remainder) % 11;
return ($chars[15] == ($result==10 ? 'X' : $result))
}
};
</source>

Additionally you will have to define a custom render to add the fields to be displayed in the abstract/summary page.

= Rendering with Bootstrap =

[[File:orcid_bootstrap.png|thumb|left|alt=ORCIDs displaying in the Bootstrap theme|ORCID and Bootstrap]]

In a recent redesign of [http://eprints.whiterose.ac.uk White Rose Research Online] the [https://github.com/eprintsug/bootstrap Bootstrap theme] was used.
The ORCID links are now enhanced with a tooltip and the green icon. There may be examples on the [http://eprints.whiterose.ac.uk/cgi/latest_tool latest 20 additions] page.

== Bootstrap tooltop ==
This block of code finds anything with a class of 'orcid', and adds the green logo to it, and a tooltip that reads 'ORCID: ''orcid-value''', as shown in the image.

The example code below is based on the following rendering of a person who may have an ORCID:
<source lang="html4strict">


Castillo Ortiz, P.J.
<a href="http://orcid.org/0000-0003-4540-1855" target="_blank" class="orcid">
orcid.org/0000-0003-4540-1855
</a>

</source>

== jQuery ==
<source lang="javascript">
// selector used here depends on your rendering. You may want to use something like a[href*='orcid.org/0000-']
jQuery('.orcid').tooltip({
'placement': 'auto',
'title': function(){ return "ORCID: "+ jQuery(this).text()},
}).append('<img src="/images/orcid_16x16.png" alt="" />').find('span').hide();
</source>

== CSS ==
The green colouring is added using the following css, which also makes the background of the tooltip opaque, not semi-transparent as it is by default.
<source lang="css">
.person + .tooltip > .tooltip-inner,
.orcid + .tooltip > .tooltip-inner {
background-color: #A6CE39;
border: 1px solid #000000;
white-space: pre;
max-width: none;
}
.person + .tooltip.in,
.orcid + .tooltip.in {
opacity: 1;
filter: alpha(opacity=100);
}
/* This adds a green dashed line under an author's name when hovered. This helps in big author lists to tie initials and surname together */
.person:hover {border-bottom: 1px dashed #a6ce39;}
.orcid a:hover {
color: #a6ce39;
}
</source>

= OAI-PMH (Experimental) =
'''[[User:Libjlrs]] 2016-09-29 Warning: this is experimental. I hope others will read, understand, question and improve on this before it becomes some form of best practice!'''

Some metadata profiles support attributes that are useful to propagate ORCIDs e.g. RIOXX (see the [[#Exposing_the_ORCID_in_RIOXX]] section above, and the 'rioxxterms:author' section on http://www.rioxx.net/profiles/v2-0-final/ ).

A lot of harvesters use the oai_dc metadata profile when harvesting records. The DC schema doesn't allow attributes on the dc:creator element, so ORCIDs cannot be added in a sensible way to this profile.

The details below create an additional metadata prefix that adds an attribute to the dc:creator field. The original <code>metadataPrefix=oai_dc</code> output remains unchanged. Using <code>metadataPrefix=oai_dc_orcid</code> will add the orcid attribute where available.

Currently there is not an XSD that describes this change, so a harvester that validates the feed may stop when it encounters an ORCID.

This example is based on the <code>EPrints::Plugin::Export::OAI_DC</code> module from EPrints 3.3.10. You may need to tweak it to make it work for you!

File: <code>~/archives/ARCHIVEID/cfg/plugins/EPrints/Plugin/Export/OAI_DC_ORCID.pm</code>
<source lang="perl">
package EPrints::Plugin::Export::OAI_DC_ORCID;

use EPrints::Plugin::Export::OAI_DC;

@ISA = ( "EPrints::Plugin::Export::OAI_DC", "EPrints::Plugin::Export::DC" );

use strict;

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

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

$self->{name} = "Dublin Core - OAI + ORCID Schema";
$self->{accept} = [ 'dataobj/eprint' ];
$self->{visible} = "";
$self->{suffix} = ".xml";
$self->{mimetype} = "text/xml";

$self->{metadataPrefix} = "oai_dc_orcid";
$self->{xmlns} = "http://www.openarchives.org/OAI/2.0/oai_dc/";
$self->{schemaLocation} = "http://www.openarchives.org/OAI/2.0/oai_dc.xsd";

return $self;
}

sub xml_dataobj
{
my( $plugin, $dataobj ) = @_;

my $data = $plugin->convert_dataobj( $dataobj );

my $dc = $plugin->{session}->make_element(
"oai_dc:dc",
"xmlns:oai_dc" => "http://www.openarchives.org/OAI/2.0/oai_dc/",
"xmlns:dc" => "http://purl.org/dc/elements/1.1/",
"xmlns:xsi" => "http://www.w3.org/2001/XMLSchema-instance",
"xsi:schemaLocation" =>
"http://www.openarchives.org/OAI/2.0/oai_dc/ http://www.openarchives.org/OAI/2.0/oai_dc.xsd" );

# turn the list of pairs into XML blocks (indented by 8) and add them
# them to the DC element.
foreach( @{$data} )
{
$dc->appendChild( $plugin->{session}->render_data_element( 8, "dc:".$_->[0], $_->[1], %{$_->[2]} ) );
# produces <key>value</key>
}

return $dc;
}

sub convert_dataobj
{
my( $plugin, $eprint ) = @_;

my $dataset = $eprint->{dataset};

my @dcdata = ();

push @dcdata, $plugin->simple_value( $eprint, title => "title" );

if( $eprint->exists_and_set( "creators" ) )
{
my $creators = $eprint->get_value( "creators" );
foreach my $creator ( @$creators )
{
next if !defined $creator;

# NOTE THIS IS VERY CRUDE, and should be replaced with more elegant methods (possibly from examples elsewhere on this page).
if( defined $creator->{id} && $creator->{id} =~ /0000/ ){
push @dcdata, [ "creator", EPrints::Utils::make_name_string( $creator->{name} ), { 'orcid' => $creator->{id} } ];
} else {
push @dcdata, [ "creator", EPrints::Utils::make_name_string( $creator->{name} ) ];
}
}
}

if( $eprint->exists_and_set( "subjects" ) )
{
my $subjectid;
foreach $subjectid ( @{$eprint->get_value( "subjects" )} )
{
my $subject = EPrints::DataObj::Subject->new( $plugin->{session}, $subjectid );
# avoid problems with bad subjects
next unless( defined $subject );
push @dcdata, [ "subject", EPrints::Utils::tree_to_utf8( $subject->render_description() ) ];
}
}

push @dcdata, $plugin->simple_value( $eprint, abstract => "description" );
push @dcdata, $plugin->simple_value( $eprint, publisher => "publisher" );

if( $eprint->exists_and_set( "editors_name" ) )
{
my $editors = $eprint->get_value( "editors_name" );
if( defined $editors )
{
foreach my $editor ( @{$editors} )
{
push @dcdata, [ "contributor", EPrints::Utils::make_name_string( $editor ) ];
}
}
}
## Date for discovery. For a month/day we don't have, assume 01.
if( $eprint->exists_and_set( "date" ) )
{
my $date = $eprint->get_value( "date" );
if( defined $date )
{
$date =~ s/(-0+)+$//;
push @dcdata, [ "date", $date ];
}
}

if( $eprint->exists_and_set( "type" ) )
{
push @dcdata, [ "type", EPrints::Utils::tree_to_utf8( $eprint->render_value( "type" ) ) ];
}

my $ref = "NonPeerReviewed";
if( $eprint->exists_and_set( "refereed" ) && $eprint->get_value( "refereed" ) eq "TRUE" )
{
$ref = "PeerReviewed";
}
push @dcdata, [ "type", $ref ];

my @documents = $eprint->get_all_documents();
my $mimetypes = $plugin->{session}->get_repository->get_conf( "oai", "mime_types" );
foreach( @documents )
{
my $format = $mimetypes->{$_->get_value("format")};
$format = $_->get_value("format") unless defined $format;
#$format = "application/octet-stream" unless defined $format;
push @dcdata, [ "format", $format ];
push @dcdata, [ "identifier", $_->get_url() ];
}

# Most commonly a DOI or journal link
push @dcdata, $plugin->simple_value( $eprint, official_url => "relation" );

# The citation for this eprint
push @dcdata, [ "identifier",
EPrints::Utils::tree_to_utf8( $eprint->render_citation() ) ];

# The URL of the abstract page
if( $eprint->is_set( "eprintid" ) )
{
push @dcdata, [ "relation", $eprint->get_url() ];
}
# dc.language not handled yet.
# dc.source not handled yet.
# dc.coverage not handled yet.
# dc.rights not handled yet.

return \@dcdata;
}

1;
</source>

ORCID

2016-10-27T14:15:52Z

Alan.stiles@open.ac.uk: /* User Object */ capital 'O'

This page has been created to gather information about how different EPrints repositories have integrated ORCID.
At this time (April 2016) there doesn't seem to be a 'best practice' approach that has been adopted widely - this will hopefully change over time.

==Field Recommendations==
As at 2016-10-18 these are the recommended field names and types as discussed at the Jisc ORCID hack day in London - Alan Stiles, John Salter, Adam Vials Moore, Peter West, Andrew Beeken

===New MetaField Type===
* Type 'Orcid' is a subtype of 'id', provides validation and render methods
N.B. Store the 16 digit, hyphen separated value, without the authority (host) details e.g. 'nnnn-nnnn-nnnn-nnnn' (as per the value returned by the ORCID API)

===User Object===
*new field named 'orcid', type 'Orcid' to store the value of the ORCID id for that user

====Suggested fields====
*'orcid_auth_code', type text - to hold the long authorisation token returned by the ORCID API at the end of a successful OAuth2 process
*'orcid_granted_permissions', type text - to hold the permissions granted via the ORCID API during the authorisation process
*'orcid_token_expires', type time - to hold the expiry timestamp for the authorisation code above (time now plus expires duration returned by the ORCID API)
*'orcid_last_update_timestamp', type text - to hold the timestamp of the last time the user's ORCID record was processed, to enable quicker reprocessing in the future.
*'orcid_webhook_ref', type text - to hold the value provided when configuring the webhook notification to validate new notifications have come from ORCID

Also potential fields for requested permissions .e.g. boolean flags or text to capture auth codes if individual permissions captured separately? (e.g. Peter West work)

===Eprints Contributors (e.g. creators, editors)===
*new sub-field of contributor_orcid (e.g. creator_orcid, editor_orcid) type 'orcid' to store the value of the ORCID id for that contributor

==Previous Discussions==
If you are looking to retrieve publications from the ORCID service, the [http://bazaar.eprints.org/354/ Import from ORCID (Tier 1 API)] Bazaar package, or the [https://github.com/eprintsug/orcidt2 ORCID Tier 2 api framework] are good places to start.

2016-05-20 [[User:Alan.stiles@open.ac.uk|Alan Stiles]] at The Open University is working on a plugin to connect EPrints with ORCID via the Tier 2 Members API to retrieve ORCID ids and synchronise publications and affiliation details.

Some aspects that need to be considered when adopting ORCIDs, and making them available to other systems are:

* storing the ORCID (see: http://support.orcid.org/knowledgebase/articles/116780-structure-of-the-orcid-identifier)
* rendering the ORCID in abstract pages (see [http://support.orcid.org/knowledgebase/articles/116780-structure-of-the-orcid-identifier link above])
* exposing ORCIDs over OAI-PMH metadata profiles e.g. RIOXX

NB The examples below may refer to the 'creators' field - but the same approach could be used to extend other 'person' fields - e.g. contributors.

= Re-using creators.id subfield =

The creators.id field is labelled 'email' by default, but as it's an 'id' type field, it can be used to store ORCIDs.
To re-label the field, a simple addition to a phrase file in <code>archives/ARCHIVEID/cfg/lang/en/phrases/</code> needs to be made:
<source lang="xml">
<epp:phrase id="eprint_fieldname_creators_id">ORCID / Creators email (if known)</epp:phrase>
</source>

== Rendering the ORCID in a citation ==
The rendering of this field then needs to be changed to accommodate an author with an ORCID. The following script adds methods that can be called via the EPScript language:

<source lang="perl">
# add to e.g. ~/archives/ARCHIVEID/cfg/cfg.d/z_add_to_EPrints_Script_Compiled.pl
# Write into EPrints::Script::Compiled package to allow use of function in epscript
{
package EPrints::Script::Compiled;
use strict;

sub run_wrro_people_with_orcids
{
my( $self, $state, $value ) = @_;

my $session = $state->{session};
my $r = $state->{session}->make_doc_fragment;

my $creators = $value->[0];

foreach my $i (0..$#$creators){

my $creator = @$creators[$i];

if( $i > 0 ){
#not first item (or only one item)
if( $i == $#$creators ){
#last item
$r->appendChild( $session->make_text( " and " ) );
} else {
$r->appendChild( $session->make_text( ", " ) );
}
}

my $person_span = $session->make_element( "span", "class" => "person" );
$person_span->appendChild( $session->render_name( $creator->{name} ) );

my $id = $creator->{id};
if( defined $id && $id =~ m/^(?:orcid.org\/)?(\d{4}\-\d{4}\-\d{4}\-\d{3}(?:\d|X))$/ )
{
my $orcid_span = $session->make_element( "span", "class" => "orcid" );

# According to https://orcid.org/trademark-and-id-display-guidelines
# "recommended display is a hyperlinked URI preceded by the iD icon"
# This looks terrible in a citation. Removed for the time being.
#
# my $orcid_link = $session->make_element(
# "a",
# "href" => "http://orcid.org/",
# "target" => "_blank",
# "class" => "orcid-icon"
# );
# $orcid_link->appendChild( $session->make_element(
# "img",
# "src" => "/images/orcid_16x16.png",
# "title" => "ORCID"
# ) );
# $orcid_span->appendChild( $orcid_link );

my $link = $session->make_element(
"a",
"href" => "http://orcid.org/$1",
"target" => "_blank",
);
$link->appendChild( $session->make_text( "orcid.org/$1" ) );

$orcid_span->appendChild( $session->make_text( "(" ) );
$orcid_span->appendChild( $link );
$orcid_span->appendChild( $session->make_text( ")" ) );

$person_span->appendChild( $session->make_text( " " ) );
$person_span->appendChild( $orcid_span );
}
$r->appendChild( $person_span );
}

return [ $r, "XHTML" ];
}

}
# END EPrints::Script::Compiled additions
</source>

You may also want a bit of CSS to style ORCID links
<source lang="css">
/* Add to e.g. ~/archives/ARCHIVEID/cfg/static/style/auto/zzz_orcid.css */
.person:hover {border-bottom: 1px dashed #a6ce39;}
.orcid {}
.orcid a:hover {
color: #a6ce39;
}
.orcid-icon {}
.orcid-icon img { vertical-align: text-bottom; margin: 0 4px 0 2px; }
</source>

And finally, you have to call the new EPScript function from a citation file e.g. <code>archives/ARCHIVEID/cfg/citations/eprint/default.xml</code>
<source lang="xml">

<print expr="wrro_people_with_orcids(creators)" />
</source>

== Exposing the ORCID in RIOXX ==
Based on re-using the creators.id field, this block of code over-writes the default <code>rioxx2_value_author</code> function.
<source lang="perl">
# Add to e.g. ~/archives/ARCHIVEID/cfg/cfg.d/zzz_rioxx2_overwrites.pl
$c->{rioxx2_value_author} = sub {
my( $eprint ) = @_;

my @authors;
for( @{ $eprint->value( "creators" ) } )
{
my $id = $_->{id}; # if you use a custom 'orcid' field, reference that here instead of 'id'
if( defined $id && $id =~ m/^(?:orcid.org\/)?(\d{4}\-\d{4}\-\d{4}\-\d{3}(?:\d|X))$/ )
{
push @authors, {
author => EPrints::Utils::make_name_string( $_->{name} ),
id => "http://orcid.org/$1"
};
} else {
push @authors, {
author => EPrints::Utils::make_name_string( $_->{name} ),
};
}
}

#NB If your corp_creators has DOIs or ISNIs for the entries, a similar method could be used to include these here.
foreach my $corp ( @{ $eprint->value( "corp_creators" ) } )
{
my $entry = {};
$entry->{name} = $corp;
push @authors, { author => $corp };
}

return \@authors;
};

</source>

= Add additional identifiers to creators =
Another approach to storing ORCIDs is to add an additional sub-field to the creator field.
This has been discussed on the Eprints tech list. If you know how to do this, please document it here!

This is how University of Bath has done it. We're getting the ORCID data from another system, so have used a text field to capture it for display. At present there is no special rendering on it, it's just displaying as a number.
<source lang="perl">
{
name => 'creators',
type => 'compound',
multiple => 1,
fields => [
{
sub_name => 'name',
type => 'name',
hide_honourific => 1,
hide_lineage => 1,
family_first => 1,
},
{
sub_name => 'id',
type => 'text',
input_cols => 20,
allow_null => 1,
},
{
sub_name => 'orcid',
type => 'text',
input_cols => 20,
allow_null => 1,
}

],
input_boxes => 4,
},
</source>
This is how University of Pittsburgh has done it:
<source lang="perl">
{
'name' => 'creators',
'type' => 'compound',
'multiple' => 1,
'fields' => [
{
'sub_name' => 'name',
'type' => 'name',
'hide_honourific' => 1,
'hide_lineage' => 1,
'family_first' => 1,
},
{
'sub_name' => 'email',
'type' => 'text',
'input_cols' => 20,
'allow_null' => 1,
},
{
'sub_name' => 'id',
'type' => 'text',
'input_cols' => 20,
'allow_null' => 1,
},
{
'sub_name' => 'orcid',
'type' => 'id',
'input_cols' => 19,
'allow_null' => 1,
},
],
'input_boxes' => 4,
'render_value' => 'custom_render_creators_with_orcid',
},

</source>

==Notes from Pittsburgh:==
(Information courtesy of Brian Gregg - bdgregg@pitt.edu)

We have added some ORCID functionality in our IR System here at the University of Pittsburgh. We however have not “linked” our IR with orcid.org in anyway such as we do not have a lookup user in ORCID or the ability to add publications from ORCID to our IR. The only link is the entering of the ORCID into the system so that it can be displayed.

An example record is available here: [http://d-scholarship.pitt.edu/28114/ http://d-scholarship.pitt.edu/28114/]

# Users have an ORCID field in their profile – user_fields.pl
# Any “Creator” types have an ORCID field added to the workflow – eprint_fields.pl
# We have added ORCID validation adhering to this document: [http://support.orcid.org/knowledgebase/articles/116780-structure-of-the-orcid-identifier] - eprint_validate.pl
# We have added the ORCID to the “lookup” function to populate the ORCID field from any user entries in the database. – cgi/users/lookup/name
# We display the ORCID as such on the input form, where the green icon links out to our own orcid.pitt.edu site, but could be to orcid.org by default.
# We display the ORCID as such on the public display of the record where the ORCID is linked out to orcid.org (see [http://d-scholarship.pitt.edu/28114/ example record])

ORCID Validator - snippet for eprints_validate.pl
<source lang="perl">
# ORCID ID Validator for individuals
# Reference: http://support.orcid.org/knowledgebase/articles/116780-structure-of-the-orcid-identifier
# REGEX: ^\d{4}-\d{4}-\d{4}-(\d{3}X|\d{4})$
#
my @name_fields = qw( creators contributors exhibitors producers conductors lyricists ); #which ever name fields you added 'orcid' to.
foreach my $name_field ( @name_fields )
{
if( $eprint->is_set( $name_field ) )
{
foreach my $creator ( @{ $eprint->value( $name_field ) } )
{
my $orcid = $creator->{orcid};
next unless defined $orcid;
if ($repository->get_repository->can_call ( "validators", "isValidORCID" ) )
{
if (!$repository->get_repository->call( [ "validators", "isValidORCID" ], $orcid ))
{
my $field_text = $repository->html_phrase( "eprint_fieldname_$name_field" );
my $field_frag = $repository->make_element( "span", class=>"ep_problem_field:$name_field" );
$field_frag->appendChild($field_text);
push @problems, $repository->html_phrase( "warnings:orcid_invalid",
orcid => $repository->get_repository->make_text($orcid),
field => $field_frag,
);
}
} else {
$repository->get_repository->log( "Can not call isValidORCID." );
}
}
}
}
</source>

Phrase for "warnings:orcid_invalid":

<source lang="xml">
<epp:phrase id="warnings:orcid_invalid">The ORCID ID: <epc:pin name="orcid"/> is not a valid ORCID ID as it does not conform to the ORCID ID specification. Please edit the <epc:pin name="field"/> with the associated ORCID or remove it from the name completely.</epp:phrase>
</source>

Additional Function that can be placed either at the end of eprints_validate.pl (after the final };) or elsewhere:
<source lang="perl">
############################################
# Function: isValidORCID
# Description: Used to validate ORCID IDs
#
# From: http://support.orcid.org/knowledgebase/articles/116780-structure-of-the-orcid-identifier (Checksum)
#
$c->{validators}->{isValidORCID} = sub {
my $ORCID = $_[0];
#Check for valid length of 19 characters.
my $size = length($ORCID);
if ($size > 19 )
{
return 0;
} else {
#Check actual validity of the ID mathematically.
$ORCID =~ s/\-//g;
my @chars = split(//, $ORCID);
my $total = 0;
for ( my $i=0; $i<15; $i++) {
$total = ($total + $chars[$i]) *2;
}
my $remainder = $total % 11;
my $result = (12 - $remainder) % 11;
return ($chars[15] == ($result==10 ? 'X' : $result))
}
};
</source>

Additionally you will have to define a custom render to add the fields to be displayed in the abstract/summary page.

= Rendering with Bootstrap =

[[File:orcid_bootstrap.png|thumb|left|alt=ORCIDs displaying in the Bootstrap theme|ORCID and Bootstrap]]

In a recent redesign of [http://eprints.whiterose.ac.uk White Rose Research Online] the [https://github.com/eprintsug/bootstrap Bootstrap theme] was used.
The ORCID links are now enhanced with a tooltip and the green icon. There may be examples on the [http://eprints.whiterose.ac.uk/cgi/latest_tool latest 20 additions] page.

== Bootstrap tooltop ==
This block of code finds anything with a class of 'orcid', and adds the green logo to it, and a tooltip that reads 'ORCID: ''orcid-value''', as shown in the image.

The example code below is based on the following rendering of a person who may have an ORCID:
<source lang="html4strict">


Castillo Ortiz, P.J.
<a href="http://orcid.org/0000-0003-4540-1855" target="_blank" class="orcid">
orcid.org/0000-0003-4540-1855
</a>

</source>

== jQuery ==
<source lang="javascript">
// selector used here depends on your rendering. You may want to use something like a[href*='orcid.org/0000-']
jQuery('.orcid').tooltip({
'placement': 'auto',
'title': function(){ return "ORCID: "+ jQuery(this).text()},
}).append('<img src="/images/orcid_16x16.png" alt="" />').find('span').hide();
</source>

== CSS ==
The green colouring is added using the following css, which also makes the background of the tooltip opaque, not semi-transparent as it is by default.
<source lang="css">
.person + .tooltip > .tooltip-inner,
.orcid + .tooltip > .tooltip-inner {
background-color: #A6CE39;
border: 1px solid #000000;
white-space: pre;
max-width: none;
}
.person + .tooltip.in,
.orcid + .tooltip.in {
opacity: 1;
filter: alpha(opacity=100);
}
/* This adds a green dashed line under an author's name when hovered. This helps in big author lists to tie initials and surname together */
.person:hover {border-bottom: 1px dashed #a6ce39;}
.orcid a:hover {
color: #a6ce39;
}
</source>

= OAI-PMH (Experimental) =
'''[[User:Libjlrs]] 2016-09-29 Warning: this is experimental. I hope others will read, understand, question and improve on this before it becomes some form of best practice!'''

Some metadata profiles support attributes that are useful to propagate ORCIDs e.g. RIOXX (see the [[#Exposing_the_ORCID_in_RIOXX]] section above, and the 'rioxxterms:author' section on http://www.rioxx.net/profiles/v2-0-final/ ).

A lot of harvesters use the oai_dc metadata profile when harvesting records. The DC schema doesn't allow attributes on the dc:creator element, so ORCIDs cannot be added in a sensible way to this profile.

The details below create an additional metadata prefix that adds an attribute to the dc:creator field. The original <code>metadataPrefix=oai_dc</code> output remains unchanged. Using <code>metadataPrefix=oai_dc_orcid</code> will add the orcid attribute where available.

Currently there is not an XSD that describes this change, so a harvester that validates the feed may stop when it encounters an ORCID.

This example is based on the <code>EPrints::Plugin::Export::OAI_DC</code> module from EPrints 3.3.10. You may need to tweak it to make it work for you!

File: <code>~/archives/ARCHIVEID/cfg/plugins/EPrints/Plugin/Export/OAI_DC_ORCID.pm</code>
<source lang="perl">
package EPrints::Plugin::Export::OAI_DC_ORCID;

use EPrints::Plugin::Export::OAI_DC;

@ISA = ( "EPrints::Plugin::Export::OAI_DC", "EPrints::Plugin::Export::DC" );

use strict;

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

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

$self->{name} = "Dublin Core - OAI + ORCID Schema";
$self->{accept} = [ 'dataobj/eprint' ];
$self->{visible} = "";
$self->{suffix} = ".xml";
$self->{mimetype} = "text/xml";

$self->{metadataPrefix} = "oai_dc_orcid";
$self->{xmlns} = "http://www.openarchives.org/OAI/2.0/oai_dc/";
$self->{schemaLocation} = "http://www.openarchives.org/OAI/2.0/oai_dc.xsd";

return $self;
}

sub xml_dataobj
{
my( $plugin, $dataobj ) = @_;

my $data = $plugin->convert_dataobj( $dataobj );

my $dc = $plugin->{session}->make_element(
"oai_dc:dc",
"xmlns:oai_dc" => "http://www.openarchives.org/OAI/2.0/oai_dc/",
"xmlns:dc" => "http://purl.org/dc/elements/1.1/",
"xmlns:xsi" => "http://www.w3.org/2001/XMLSchema-instance",
"xsi:schemaLocation" =>
"http://www.openarchives.org/OAI/2.0/oai_dc/ http://www.openarchives.org/OAI/2.0/oai_dc.xsd" );

# turn the list of pairs into XML blocks (indented by 8) and add them
# them to the DC element.
foreach( @{$data} )
{
$dc->appendChild( $plugin->{session}->render_data_element( 8, "dc:".$_->[0], $_->[1], %{$_->[2]} ) );
# produces <key>value</key>
}

return $dc;
}

sub convert_dataobj
{
my( $plugin, $eprint ) = @_;

my $dataset = $eprint->{dataset};

my @dcdata = ();

push @dcdata, $plugin->simple_value( $eprint, title => "title" );

if( $eprint->exists_and_set( "creators" ) )
{
my $creators = $eprint->get_value( "creators" );
foreach my $creator ( @$creators )
{
next if !defined $creator;

# NOTE THIS IS VERY CRUDE, and should be replaced with more elegant methods (possibly from examples elsewhere on this page).
if( defined $creator->{id} && $creator->{id} =~ /0000/ ){
push @dcdata, [ "creator", EPrints::Utils::make_name_string( $creator->{name} ), { 'orcid' => $creator->{id} } ];
} else {
push @dcdata, [ "creator", EPrints::Utils::make_name_string( $creator->{name} ) ];
}
}
}

if( $eprint->exists_and_set( "subjects" ) )
{
my $subjectid;
foreach $subjectid ( @{$eprint->get_value( "subjects" )} )
{
my $subject = EPrints::DataObj::Subject->new( $plugin->{session}, $subjectid );
# avoid problems with bad subjects
next unless( defined $subject );
push @dcdata, [ "subject", EPrints::Utils::tree_to_utf8( $subject->render_description() ) ];
}
}

push @dcdata, $plugin->simple_value( $eprint, abstract => "description" );
push @dcdata, $plugin->simple_value( $eprint, publisher => "publisher" );

if( $eprint->exists_and_set( "editors_name" ) )
{
my $editors = $eprint->get_value( "editors_name" );
if( defined $editors )
{
foreach my $editor ( @{$editors} )
{
push @dcdata, [ "contributor", EPrints::Utils::make_name_string( $editor ) ];
}
}
}
## Date for discovery. For a month/day we don't have, assume 01.
if( $eprint->exists_and_set( "date" ) )
{
my $date = $eprint->get_value( "date" );
if( defined $date )
{
$date =~ s/(-0+)+$//;
push @dcdata, [ "date", $date ];
}
}

if( $eprint->exists_and_set( "type" ) )
{
push @dcdata, [ "type", EPrints::Utils::tree_to_utf8( $eprint->render_value( "type" ) ) ];
}

my $ref = "NonPeerReviewed";
if( $eprint->exists_and_set( "refereed" ) && $eprint->get_value( "refereed" ) eq "TRUE" )
{
$ref = "PeerReviewed";
}
push @dcdata, [ "type", $ref ];

my @documents = $eprint->get_all_documents();
my $mimetypes = $plugin->{session}->get_repository->get_conf( "oai", "mime_types" );
foreach( @documents )
{
my $format = $mimetypes->{$_->get_value("format")};
$format = $_->get_value("format") unless defined $format;
#$format = "application/octet-stream" unless defined $format;
push @dcdata, [ "format", $format ];
push @dcdata, [ "identifier", $_->get_url() ];
}

# Most commonly a DOI or journal link
push @dcdata, $plugin->simple_value( $eprint, official_url => "relation" );

# The citation for this eprint
push @dcdata, [ "identifier",
EPrints::Utils::tree_to_utf8( $eprint->render_citation() ) ];

# The URL of the abstract page
if( $eprint->is_set( "eprintid" ) )
{
push @dcdata, [ "relation", $eprint->get_url() ];
}
# dc.language not handled yet.
# dc.source not handled yet.
# dc.coverage not handled yet.
# dc.rights not handled yet.

return \@dcdata;
}

1;
</source>

ORCID

2016-10-27T14:15:18Z

Alan.stiles@open.ac.uk: /* Field Recommendations */ capitalise O of Orcid metafield type

This page has been created to gather information about how different EPrints repositories have integrated ORCID.
At this time (April 2016) there doesn't seem to be a 'best practice' approach that has been adopted widely - this will hopefully change over time.

==Field Recommendations==
As at 2016-10-18 these are the recommended field names and types as discussed at the Jisc ORCID hack day in London - Alan Stiles, John Salter, Adam Vials Moore, Peter West, Andrew Beeken

===New MetaField Type===
* Type 'Orcid' is a subtype of 'id', provides validation and render methods
N.B. Store the 16 digit, hyphen separated value, without the authority (host) details e.g. 'nnnn-nnnn-nnnn-nnnn' (as per the value returned by the ORCID API)

===User Object===
*new field named 'orcid', type 'orcid' to store the value of the ORCID id for that user

====Suggested fields====
*'orcid_auth_code', type text - to hold the long authorisation token returned by the ORCID API at the end of a successful OAuth2 process
*'orcid_granted_permissions', type text - to hold the permissions granted via the ORCID API during the authorisation process
*'orcid_token_expires', type time - to hold the expiry timestamp for the authorisation code above (time now plus expires duration returned by the ORCID API)
*'orcid_last_update_timestamp', type text - to hold the timestamp of the last time the user's ORCID record was processed, to enable quicker reprocessing in the future.
*'orcid_webhook_ref', type text - to hold the value provided when configuring the webhook notification to validate new notifications have come from ORCID

Also potential fields for requested permissions .e.g. boolean flags or text to capture auth codes if individual permissions captured separately? (e.g. Peter West work)

===Eprints Contributors (e.g. creators, editors)===
*new sub-field of contributor_orcid (e.g. creator_orcid, editor_orcid) type 'orcid' to store the value of the ORCID id for that contributor

==Previous Discussions==
If you are looking to retrieve publications from the ORCID service, the [http://bazaar.eprints.org/354/ Import from ORCID (Tier 1 API)] Bazaar package, or the [https://github.com/eprintsug/orcidt2 ORCID Tier 2 api framework] are good places to start.

2016-05-20 [[User:Alan.stiles@open.ac.uk|Alan Stiles]] at The Open University is working on a plugin to connect EPrints with ORCID via the Tier 2 Members API to retrieve ORCID ids and synchronise publications and affiliation details.

Some aspects that need to be considered when adopting ORCIDs, and making them available to other systems are:

* storing the ORCID (see: http://support.orcid.org/knowledgebase/articles/116780-structure-of-the-orcid-identifier)
* rendering the ORCID in abstract pages (see [http://support.orcid.org/knowledgebase/articles/116780-structure-of-the-orcid-identifier link above])
* exposing ORCIDs over OAI-PMH metadata profiles e.g. RIOXX

NB The examples below may refer to the 'creators' field - but the same approach could be used to extend other 'person' fields - e.g. contributors.

= Re-using creators.id subfield =

The creators.id field is labelled 'email' by default, but as it's an 'id' type field, it can be used to store ORCIDs.
To re-label the field, a simple addition to a phrase file in <code>archives/ARCHIVEID/cfg/lang/en/phrases/</code> needs to be made:
<source lang="xml">
<epp:phrase id="eprint_fieldname_creators_id">ORCID / Creators email (if known)</epp:phrase>
</source>

== Rendering the ORCID in a citation ==
The rendering of this field then needs to be changed to accommodate an author with an ORCID. The following script adds methods that can be called via the EPScript language:

<source lang="perl">
# add to e.g. ~/archives/ARCHIVEID/cfg/cfg.d/z_add_to_EPrints_Script_Compiled.pl
# Write into EPrints::Script::Compiled package to allow use of function in epscript
{
package EPrints::Script::Compiled;
use strict;

sub run_wrro_people_with_orcids
{
my( $self, $state, $value ) = @_;

my $session = $state->{session};
my $r = $state->{session}->make_doc_fragment;

my $creators = $value->[0];

foreach my $i (0..$#$creators){

my $creator = @$creators[$i];

if( $i > 0 ){
#not first item (or only one item)
if( $i == $#$creators ){
#last item
$r->appendChild( $session->make_text( " and " ) );
} else {
$r->appendChild( $session->make_text( ", " ) );
}
}

my $person_span = $session->make_element( "span", "class" => "person" );
$person_span->appendChild( $session->render_name( $creator->{name} ) );

my $id = $creator->{id};
if( defined $id && $id =~ m/^(?:orcid.org\/)?(\d{4}\-\d{4}\-\d{4}\-\d{3}(?:\d|X))$/ )
{
my $orcid_span = $session->make_element( "span", "class" => "orcid" );

# According to https://orcid.org/trademark-and-id-display-guidelines
# "recommended display is a hyperlinked URI preceded by the iD icon"
# This looks terrible in a citation. Removed for the time being.
#
# my $orcid_link = $session->make_element(
# "a",
# "href" => "http://orcid.org/",
# "target" => "_blank",
# "class" => "orcid-icon"
# );
# $orcid_link->appendChild( $session->make_element(
# "img",
# "src" => "/images/orcid_16x16.png",
# "title" => "ORCID"
# ) );
# $orcid_span->appendChild( $orcid_link );

my $link = $session->make_element(
"a",
"href" => "http://orcid.org/$1",
"target" => "_blank",
);
$link->appendChild( $session->make_text( "orcid.org/$1" ) );

$orcid_span->appendChild( $session->make_text( "(" ) );
$orcid_span->appendChild( $link );
$orcid_span->appendChild( $session->make_text( ")" ) );

$person_span->appendChild( $session->make_text( " " ) );
$person_span->appendChild( $orcid_span );
}
$r->appendChild( $person_span );
}

return [ $r, "XHTML" ];
}

}
# END EPrints::Script::Compiled additions
</source>

You may also want a bit of CSS to style ORCID links
<source lang="css">
/* Add to e.g. ~/archives/ARCHIVEID/cfg/static/style/auto/zzz_orcid.css */
.person:hover {border-bottom: 1px dashed #a6ce39;}
.orcid {}
.orcid a:hover {
color: #a6ce39;
}
.orcid-icon {}
.orcid-icon img { vertical-align: text-bottom; margin: 0 4px 0 2px; }
</source>

And finally, you have to call the new EPScript function from a citation file e.g. <code>archives/ARCHIVEID/cfg/citations/eprint/default.xml</code>
<source lang="xml">

<print expr="wrro_people_with_orcids(creators)" />
</source>

== Exposing the ORCID in RIOXX ==
Based on re-using the creators.id field, this block of code over-writes the default <code>rioxx2_value_author</code> function.
<source lang="perl">
# Add to e.g. ~/archives/ARCHIVEID/cfg/cfg.d/zzz_rioxx2_overwrites.pl
$c->{rioxx2_value_author} = sub {
my( $eprint ) = @_;

my @authors;
for( @{ $eprint->value( "creators" ) } )
{
my $id = $_->{id}; # if you use a custom 'orcid' field, reference that here instead of 'id'
if( defined $id && $id =~ m/^(?:orcid.org\/)?(\d{4}\-\d{4}\-\d{4}\-\d{3}(?:\d|X))$/ )
{
push @authors, {
author => EPrints::Utils::make_name_string( $_->{name} ),
id => "http://orcid.org/$1"
};
} else {
push @authors, {
author => EPrints::Utils::make_name_string( $_->{name} ),
};
}
}

#NB If your corp_creators has DOIs or ISNIs for the entries, a similar method could be used to include these here.
foreach my $corp ( @{ $eprint->value( "corp_creators" ) } )
{
my $entry = {};
$entry->{name} = $corp;
push @authors, { author => $corp };
}

return \@authors;
};

</source>

= Add additional identifiers to creators =
Another approach to storing ORCIDs is to add an additional sub-field to the creator field.
This has been discussed on the Eprints tech list. If you know how to do this, please document it here!

This is how University of Bath has done it. We're getting the ORCID data from another system, so have used a text field to capture it for display. At present there is no special rendering on it, it's just displaying as a number.
<source lang="perl">
{
name => 'creators',
type => 'compound',
multiple => 1,
fields => [
{
sub_name => 'name',
type => 'name',
hide_honourific => 1,
hide_lineage => 1,
family_first => 1,
},
{
sub_name => 'id',
type => 'text',
input_cols => 20,
allow_null => 1,
},
{
sub_name => 'orcid',
type => 'text',
input_cols => 20,
allow_null => 1,
}

],
input_boxes => 4,
},
</source>
This is how University of Pittsburgh has done it:
<source lang="perl">
{
'name' => 'creators',
'type' => 'compound',
'multiple' => 1,
'fields' => [
{
'sub_name' => 'name',
'type' => 'name',
'hide_honourific' => 1,
'hide_lineage' => 1,
'family_first' => 1,
},
{
'sub_name' => 'email',
'type' => 'text',
'input_cols' => 20,
'allow_null' => 1,
},
{
'sub_name' => 'id',
'type' => 'text',
'input_cols' => 20,
'allow_null' => 1,
},
{
'sub_name' => 'orcid',
'type' => 'id',
'input_cols' => 19,
'allow_null' => 1,
},
],
'input_boxes' => 4,
'render_value' => 'custom_render_creators_with_orcid',
},

</source>

==Notes from Pittsburgh:==
(Information courtesy of Brian Gregg - bdgregg@pitt.edu)

We have added some ORCID functionality in our IR System here at the University of Pittsburgh. We however have not “linked” our IR with orcid.org in anyway such as we do not have a lookup user in ORCID or the ability to add publications from ORCID to our IR. The only link is the entering of the ORCID into the system so that it can be displayed.

An example record is available here: [http://d-scholarship.pitt.edu/28114/ http://d-scholarship.pitt.edu/28114/]

# Users have an ORCID field in their profile – user_fields.pl
# Any “Creator” types have an ORCID field added to the workflow – eprint_fields.pl
# We have added ORCID validation adhering to this document: [http://support.orcid.org/knowledgebase/articles/116780-structure-of-the-orcid-identifier] - eprint_validate.pl
# We have added the ORCID to the “lookup” function to populate the ORCID field from any user entries in the database. – cgi/users/lookup/name
# We display the ORCID as such on the input form, where the green icon links out to our own orcid.pitt.edu site, but could be to orcid.org by default.
# We display the ORCID as such on the public display of the record where the ORCID is linked out to orcid.org (see [http://d-scholarship.pitt.edu/28114/ example record])

ORCID Validator - snippet for eprints_validate.pl
<source lang="perl">
# ORCID ID Validator for individuals
# Reference: http://support.orcid.org/knowledgebase/articles/116780-structure-of-the-orcid-identifier
# REGEX: ^\d{4}-\d{4}-\d{4}-(\d{3}X|\d{4})$
#
my @name_fields = qw( creators contributors exhibitors producers conductors lyricists ); #which ever name fields you added 'orcid' to.
foreach my $name_field ( @name_fields )
{
if( $eprint->is_set( $name_field ) )
{
foreach my $creator ( @{ $eprint->value( $name_field ) } )
{
my $orcid = $creator->{orcid};
next unless defined $orcid;
if ($repository->get_repository->can_call ( "validators", "isValidORCID" ) )
{
if (!$repository->get_repository->call( [ "validators", "isValidORCID" ], $orcid ))
{
my $field_text = $repository->html_phrase( "eprint_fieldname_$name_field" );
my $field_frag = $repository->make_element( "span", class=>"ep_problem_field:$name_field" );
$field_frag->appendChild($field_text);
push @problems, $repository->html_phrase( "warnings:orcid_invalid",
orcid => $repository->get_repository->make_text($orcid),
field => $field_frag,
);
}
} else {
$repository->get_repository->log( "Can not call isValidORCID." );
}
}
}
}
</source>

Phrase for "warnings:orcid_invalid":

<source lang="xml">
<epp:phrase id="warnings:orcid_invalid">The ORCID ID: <epc:pin name="orcid"/> is not a valid ORCID ID as it does not conform to the ORCID ID specification. Please edit the <epc:pin name="field"/> with the associated ORCID or remove it from the name completely.</epp:phrase>
</source>

Additional Function that can be placed either at the end of eprints_validate.pl (after the final };) or elsewhere:
<source lang="perl">
############################################
# Function: isValidORCID
# Description: Used to validate ORCID IDs
#
# From: http://support.orcid.org/knowledgebase/articles/116780-structure-of-the-orcid-identifier (Checksum)
#
$c->{validators}->{isValidORCID} = sub {
my $ORCID = $_[0];
#Check for valid length of 19 characters.
my $size = length($ORCID);
if ($size > 19 )
{
return 0;
} else {
#Check actual validity of the ID mathematically.
$ORCID =~ s/\-//g;
my @chars = split(//, $ORCID);
my $total = 0;
for ( my $i=0; $i<15; $i++) {
$total = ($total + $chars[$i]) *2;
}
my $remainder = $total % 11;
my $result = (12 - $remainder) % 11;
return ($chars[15] == ($result==10 ? 'X' : $result))
}
};
</source>

Additionally you will have to define a custom render to add the fields to be displayed in the abstract/summary page.

= Rendering with Bootstrap =

[[File:orcid_bootstrap.png|thumb|left|alt=ORCIDs displaying in the Bootstrap theme|ORCID and Bootstrap]]

In a recent redesign of [http://eprints.whiterose.ac.uk White Rose Research Online] the [https://github.com/eprintsug/bootstrap Bootstrap theme] was used.
The ORCID links are now enhanced with a tooltip and the green icon. There may be examples on the [http://eprints.whiterose.ac.uk/cgi/latest_tool latest 20 additions] page.

== Bootstrap tooltop ==
This block of code finds anything with a class of 'orcid', and adds the green logo to it, and a tooltip that reads 'ORCID: ''orcid-value''', as shown in the image.

The example code below is based on the following rendering of a person who may have an ORCID:
<source lang="html4strict">


Castillo Ortiz, P.J.
<a href="http://orcid.org/0000-0003-4540-1855" target="_blank" class="orcid">
orcid.org/0000-0003-4540-1855
</a>

</source>

== jQuery ==
<source lang="javascript">
// selector used here depends on your rendering. You may want to use something like a[href*='orcid.org/0000-']
jQuery('.orcid').tooltip({
'placement': 'auto',
'title': function(){ return "ORCID: "+ jQuery(this).text()},
}).append('<img src="/images/orcid_16x16.png" alt="" />').find('span').hide();
</source>

== CSS ==
The green colouring is added using the following css, which also makes the background of the tooltip opaque, not semi-transparent as it is by default.
<source lang="css">
.person + .tooltip > .tooltip-inner,
.orcid + .tooltip > .tooltip-inner {
background-color: #A6CE39;
border: 1px solid #000000;
white-space: pre;
max-width: none;
}
.person + .tooltip.in,
.orcid + .tooltip.in {
opacity: 1;
filter: alpha(opacity=100);
}
/* This adds a green dashed line under an author's name when hovered. This helps in big author lists to tie initials and surname together */
.person:hover {border-bottom: 1px dashed #a6ce39;}
.orcid a:hover {
color: #a6ce39;
}
</source>

= OAI-PMH (Experimental) =
'''[[User:Libjlrs]] 2016-09-29 Warning: this is experimental. I hope others will read, understand, question and improve on this before it becomes some form of best practice!'''

Some metadata profiles support attributes that are useful to propagate ORCIDs e.g. RIOXX (see the [[#Exposing_the_ORCID_in_RIOXX]] section above, and the 'rioxxterms:author' section on http://www.rioxx.net/profiles/v2-0-final/ ).

A lot of harvesters use the oai_dc metadata profile when harvesting records. The DC schema doesn't allow attributes on the dc:creator element, so ORCIDs cannot be added in a sensible way to this profile.

The details below create an additional metadata prefix that adds an attribute to the dc:creator field. The original <code>metadataPrefix=oai_dc</code> output remains unchanged. Using <code>metadataPrefix=oai_dc_orcid</code> will add the orcid attribute where available.

Currently there is not an XSD that describes this change, so a harvester that validates the feed may stop when it encounters an ORCID.

This example is based on the <code>EPrints::Plugin::Export::OAI_DC</code> module from EPrints 3.3.10. You may need to tweak it to make it work for you!

File: <code>~/archives/ARCHIVEID/cfg/plugins/EPrints/Plugin/Export/OAI_DC_ORCID.pm</code>
<source lang="perl">
package EPrints::Plugin::Export::OAI_DC_ORCID;

use EPrints::Plugin::Export::OAI_DC;

@ISA = ( "EPrints::Plugin::Export::OAI_DC", "EPrints::Plugin::Export::DC" );

use strict;

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

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

$self->{name} = "Dublin Core - OAI + ORCID Schema";
$self->{accept} = [ 'dataobj/eprint' ];
$self->{visible} = "";
$self->{suffix} = ".xml";
$self->{mimetype} = "text/xml";

$self->{metadataPrefix} = "oai_dc_orcid";
$self->{xmlns} = "http://www.openarchives.org/OAI/2.0/oai_dc/";
$self->{schemaLocation} = "http://www.openarchives.org/OAI/2.0/oai_dc.xsd";

return $self;
}

sub xml_dataobj
{
my( $plugin, $dataobj ) = @_;

my $data = $plugin->convert_dataobj( $dataobj );

my $dc = $plugin->{session}->make_element(
"oai_dc:dc",
"xmlns:oai_dc" => "http://www.openarchives.org/OAI/2.0/oai_dc/",
"xmlns:dc" => "http://purl.org/dc/elements/1.1/",
"xmlns:xsi" => "http://www.w3.org/2001/XMLSchema-instance",
"xsi:schemaLocation" =>
"http://www.openarchives.org/OAI/2.0/oai_dc/ http://www.openarchives.org/OAI/2.0/oai_dc.xsd" );

# turn the list of pairs into XML blocks (indented by 8) and add them
# them to the DC element.
foreach( @{$data} )
{
$dc->appendChild( $plugin->{session}->render_data_element( 8, "dc:".$_->[0], $_->[1], %{$_->[2]} ) );
# produces <key>value</key>
}

return $dc;
}

sub convert_dataobj
{
my( $plugin, $eprint ) = @_;

my $dataset = $eprint->{dataset};

my @dcdata = ();

push @dcdata, $plugin->simple_value( $eprint, title => "title" );

if( $eprint->exists_and_set( "creators" ) )
{
my $creators = $eprint->get_value( "creators" );
foreach my $creator ( @$creators )
{
next if !defined $creator;

# NOTE THIS IS VERY CRUDE, and should be replaced with more elegant methods (possibly from examples elsewhere on this page).
if( defined $creator->{id} && $creator->{id} =~ /0000/ ){
push @dcdata, [ "creator", EPrints::Utils::make_name_string( $creator->{name} ), { 'orcid' => $creator->{id} } ];
} else {
push @dcdata, [ "creator", EPrints::Utils::make_name_string( $creator->{name} ) ];
}
}
}

if( $eprint->exists_and_set( "subjects" ) )
{
my $subjectid;
foreach $subjectid ( @{$eprint->get_value( "subjects" )} )
{
my $subject = EPrints::DataObj::Subject->new( $plugin->{session}, $subjectid );
# avoid problems with bad subjects
next unless( defined $subject );
push @dcdata, [ "subject", EPrints::Utils::tree_to_utf8( $subject->render_description() ) ];
}
}

push @dcdata, $plugin->simple_value( $eprint, abstract => "description" );
push @dcdata, $plugin->simple_value( $eprint, publisher => "publisher" );

if( $eprint->exists_and_set( "editors_name" ) )
{
my $editors = $eprint->get_value( "editors_name" );
if( defined $editors )
{
foreach my $editor ( @{$editors} )
{
push @dcdata, [ "contributor", EPrints::Utils::make_name_string( $editor ) ];
}
}
}
## Date for discovery. For a month/day we don't have, assume 01.
if( $eprint->exists_and_set( "date" ) )
{
my $date = $eprint->get_value( "date" );
if( defined $date )
{
$date =~ s/(-0+)+$//;
push @dcdata, [ "date", $date ];
}
}

if( $eprint->exists_and_set( "type" ) )
{
push @dcdata, [ "type", EPrints::Utils::tree_to_utf8( $eprint->render_value( "type" ) ) ];
}

my $ref = "NonPeerReviewed";
if( $eprint->exists_and_set( "refereed" ) && $eprint->get_value( "refereed" ) eq "TRUE" )
{
$ref = "PeerReviewed";
}
push @dcdata, [ "type", $ref ];

my @documents = $eprint->get_all_documents();
my $mimetypes = $plugin->{session}->get_repository->get_conf( "oai", "mime_types" );
foreach( @documents )
{
my $format = $mimetypes->{$_->get_value("format")};
$format = $_->get_value("format") unless defined $format;
#$format = "application/octet-stream" unless defined $format;
push @dcdata, [ "format", $format ];
push @dcdata, [ "identifier", $_->get_url() ];
}

# Most commonly a DOI or journal link
push @dcdata, $plugin->simple_value( $eprint, official_url => "relation" );

# The citation for this eprint
push @dcdata, [ "identifier",
EPrints::Utils::tree_to_utf8( $eprint->render_citation() ) ];

# The URL of the abstract page
if( $eprint->is_set( "eprintid" ) )
{
push @dcdata, [ "relation", $eprint->get_url() ];
}
# dc.language not handled yet.
# dc.source not handled yet.
# dc.coverage not handled yet.
# dc.rights not handled yet.

return \@dcdata;
}

1;
</source>

ORCID

2016-10-18T14:14:51Z

Alan.stiles@open.ac.uk: /* Field Recommendations */ suggested fields

This page has been created to gather information about how different EPrints repositories have integrated ORCID.
At this time (April 2016) there doesn't seem to be a 'best practice' approach that has been adopted widely - this will hopefully change over time.

==Field Recommendations==
As at 2016-10-18 these are the recommended field names and types as discussed at the Jisc ORCID hack day in London - Alan Stiles, John Salter, Adam Vials Moore, Peter West, Andrew Beeken

===New MetaField Type===
* Type 'orcid' is a subtype of 'id', provides validation and render methods
N.B. Store the 16 digit, hyphen separated value, without the authority (host) details e.g. 'nnnn-nnnn-nnnn-nnnn' (as per the value returned by the ORCID API)

===User Object===
*new field named 'orcid', type 'orcid' to store the value of the ORCID id for that user

====Suggested fields====
*'orcid_auth_code', type text - to hold the long authorisation token returned by the ORCID API at the end of a successful OAuth2 process
*'orcid_granted_permissions', type text - to hold the permissions granted via the ORCID API during the authorisation process
*'orcid_token_expires', type time - to hold the expiry timestamp for the authorisation code above (time now plus expires duration returned by the ORCID API)
*'orcid_last_update_timestamp', type text - to hold the timestamp of the last time the user's ORCID record was processed, to enable quicker reprocessing in the future.
*'orcid_webhook_ref', type text - to hold the value provided when configuring the webhook notification to validate new notifications have come from ORCID

Also potential fields for requested permissions .e.g. boolean flags or text to capture auth codes if individual permissions captured separately? (e.g. Peter West work)

===Eprints Contributors (e.g. creators, editors)===
*new sub-field of contributor_orcid (e.g. creator_orcid, editor_orcid) type 'orcid' to store the value of the ORCID id for that contributor

==Previous Discussions==
If you are looking to retrieve publications from the ORCID service, the [http://bazaar.eprints.org/354/ Import from ORCID (Tier 1 API)] Bazaar package, or the [https://github.com/eprintsug/orcidt2 ORCID Tier 2 api framework] are good places to start.

2016-05-20 [[User:Alan.stiles@open.ac.uk|Alan Stiles]] at The Open University is working on a plugin to connect EPrints with ORCID via the Tier 2 Members API to retrieve ORCID ids and synchronise publications and affiliation details.

Some aspects that need to be considered when adopting ORCIDs, and making them available to other systems are:

* storing the ORCID (see: http://support.orcid.org/knowledgebase/articles/116780-structure-of-the-orcid-identifier)
* rendering the ORCID in abstract pages (see [http://support.orcid.org/knowledgebase/articles/116780-structure-of-the-orcid-identifier link above])
* exposing ORCIDs over OAI-PMH metadata profiles e.g. RIOXX

NB The examples below may refer to the 'creators' field - but the same approach could be used to extend other 'person' fields - e.g. contributors.

= Re-using creators.id subfield =

The creators.id field is labelled 'email' by default, but as it's an 'id' type field, it can be used to store ORCIDs.
To re-label the field, a simple addition to a phrase file in <code>archives/ARCHIVEID/cfg/lang/en/phrases/</code> needs to be made:
<source lang="xml">
<epp:phrase id="eprint_fieldname_creators_id">ORCID / Creators email (if known)</epp:phrase>
</source>

== Rendering the ORCID in a citation ==
The rendering of this field then needs to be changed to accommodate an author with an ORCID. The following script adds methods that can be called via the EPScript language:

<source lang="perl">
# add to e.g. ~/archives/ARCHIVEID/cfg/cfg.d/z_add_to_EPrints_Script_Compiled.pl
# Write into EPrints::Script::Compiled package to allow use of function in epscript
{
package EPrints::Script::Compiled;
use strict;

sub run_wrro_people_with_orcids
{
my( $self, $state, $value ) = @_;

my $session = $state->{session};
my $r = $state->{session}->make_doc_fragment;

my $creators = $value->[0];

foreach my $i (0..$#$creators){

my $creator = @$creators[$i];

if( $i > 0 ){
#not first item (or only one item)
if( $i == $#$creators ){
#last item
$r->appendChild( $session->make_text( " and " ) );
} else {
$r->appendChild( $session->make_text( ", " ) );
}
}

my $person_span = $session->make_element( "span", "class" => "person" );
$person_span->appendChild( $session->render_name( $creator->{name} ) );

my $id = $creator->{id};
if( defined $id && $id =~ m/^(?:orcid.org\/)?(\d{4}\-\d{4}\-\d{4}\-\d{3}(?:\d|X))$/ )
{
my $orcid_span = $session->make_element( "span", "class" => "orcid" );

# According to https://orcid.org/trademark-and-id-display-guidelines
# "recommended display is a hyperlinked URI preceded by the iD icon"
# This looks terrible in a citation. Removed for the time being.
#
# my $orcid_link = $session->make_element(
# "a",
# "href" => "http://orcid.org/",
# "target" => "_blank",
# "class" => "orcid-icon"
# );
# $orcid_link->appendChild( $session->make_element(
# "img",
# "src" => "/images/orcid_16x16.png",
# "title" => "ORCID"
# ) );
# $orcid_span->appendChild( $orcid_link );

my $link = $session->make_element(
"a",
"href" => "http://orcid.org/$1",
"target" => "_blank",
);
$link->appendChild( $session->make_text( "orcid.org/$1" ) );

$orcid_span->appendChild( $session->make_text( "(" ) );
$orcid_span->appendChild( $link );
$orcid_span->appendChild( $session->make_text( ")" ) );

$person_span->appendChild( $session->make_text( " " ) );
$person_span->appendChild( $orcid_span );
}
$r->appendChild( $person_span );
}

return [ $r, "XHTML" ];
}

}
# END EPrints::Script::Compiled additions
</source>

You may also want a bit of CSS to style ORCID links
<source lang="css">
/* Add to e.g. ~/archives/ARCHIVEID/cfg/static/style/auto/zzz_orcid.css */
.person:hover {border-bottom: 1px dashed #a6ce39;}
.orcid {}
.orcid a:hover {
color: #a6ce39;
}
.orcid-icon {}
.orcid-icon img { vertical-align: text-bottom; margin: 0 4px 0 2px; }
</source>

And finally, you have to call the new EPScript function from a citation file e.g. <code>archives/ARCHIVEID/cfg/citations/eprint/default.xml</code>
<source lang="xml">

<print expr="wrro_people_with_orcids(creators)" />
</source>

== Exposing the ORCID in RIOXX ==
Based on re-using the creators.id field, this block of code over-writes the default <code>rioxx2_value_author</code> function.
<source lang="perl">
# Add to e.g. ~/archives/ARCHIVEID/cfg/cfg.d/zzz_rioxx2_overwrites.pl
$c->{rioxx2_value_author} = sub {
my( $eprint ) = @_;

my @authors;
for( @{ $eprint->value( "creators" ) } )
{
my $id = $_->{id};
if( defined $id && $id =~ m/^(?:orcid.org\/)?(\d{4}\-\d{4}\-\d{4}\-\d{3}(?:\d|X))$/ )
{
push @authors, {
author => EPrints::Utils::make_name_string( $_->{name} ),
id => "http://orcid.org/$1"
};
} else {
push @authors, {
author => EPrints::Utils::make_name_string( $_->{name} ),
};
}
}

#NB If your corp_creators has DOIs or ISNIs for the entries, a similar method could be used to include these here.
foreach my $corp ( @{ $eprint->value( "corp_creators" ) } )
{
my $entry = {};
$entry->{name} = $corp;
push @authors, { author => $corp };
}

return \@authors;
};

</source>

= Add additional identifiers to creators =
Another approach to storing ORCIDs is to add an additional sub-field to the creator field.
This has been discussed on the Eprints tech list. If you know how to do this, please document it here!

This is how University of Bath has done it. We're getting the ORCID data from another system, so have used a text field to capture it for display. At present there is no special rendering on it, it's just displaying as a number.
<source lang="perl">
{
name => 'creators',
type => 'compound',
multiple => 1,
fields => [
{
sub_name => 'name',
type => 'name',
hide_honourific => 1,
hide_lineage => 1,
family_first => 1,
},
{
sub_name => 'id',
type => 'text',
input_cols => 20,
allow_null => 1,
},
{
sub_name => 'orcid',
type => 'text',
input_cols => 20,
allow_null => 1,
}

],
input_boxes => 4,
},
</source>
This is how University of Pittsburgh has done it:
<source lang="perl">
{
'name' => 'creators',
'type' => 'compound',
'multiple' => 1,
'fields' => [
{
'sub_name' => 'name',
'type' => 'name',
'hide_honourific' => 1,
'hide_lineage' => 1,
'family_first' => 1,
},
{
'sub_name' => 'email',
'type' => 'text',
'input_cols' => 20,
'allow_null' => 1,
},
{
'sub_name' => 'id',
'type' => 'text',
'input_cols' => 20,
'allow_null' => 1,
},
{
'sub_name' => 'orcid',
'type' => 'id',
'input_cols' => 19,
'allow_null' => 1,
},
],
'input_boxes' => 4,
'render_value' => 'custom_render_creators_with_orcid',
},

</source>

==Notes from Pittsburgh:==
(Information courtesy of Brian Gregg - bdgregg@pitt.edu)

We have added some ORCID functionality in our IR System here at the University of Pittsburgh. We however have not “linked” our IR with orcid.org in anyway such as we do not have a lookup user in ORCID or the ability to add publications from ORCID to our IR. The only link is the entering of the ORCID into the system so that it can be displayed.

An example record is available here: [http://d-scholarship.pitt.edu/28114/ http://d-scholarship.pitt.edu/28114/]

# Users have an ORCID field in their profile – user_fields.pl
# Any “Creator” types have an ORCID field added to the workflow – eprint_fields.pl
# We have added ORCID validation adhering to this document: [http://support.orcid.org/knowledgebase/articles/116780-structure-of-the-orcid-identifier] - eprint_validate.pl
# We have added the ORCID to the “lookup” function to populate the ORCID field from any user entries in the database. – cgi/users/lookup/name
# We display the ORCID as such on the input form, where the green icon links out to our own orcid.pitt.edu site, but could be to orcid.org by default.
# We display the ORCID as such on the public display of the record where the ORCID is linked out to orcid.org (see [http://d-scholarship.pitt.edu/28114/ example record])

ORCID Validator - snippet for eprints_validate.pl
<source lang="perl">
# ORCID ID Validator for individuals
# Reference: http://support.orcid.org/knowledgebase/articles/116780-structure-of-the-orcid-identifier
# REGEX: ^\d{4}-\d{4}-\d{4}-(\d{3}X|\d{4})$
#
my @name_fields = qw( creators contributors exhibitors producers conductors lyricists ); #which ever name fields you added 'orcid' to.
foreach my $name_field ( @name_fields )
{
if( $eprint->is_set( $name_field ) )
{
foreach my $creator ( @{ $eprint->value( $name_field ) } )
{
my $orcid = $creator->{orcid};
next unless defined $orcid;
if ($repository->get_repository->can_call ( "validators", "isValidORCID" ) )
{
if (!$repository->get_repository->call( [ "validators", "isValidORCID" ], $orcid ))
{
my $field_text = $repository->html_phrase( "eprint_fieldname_$name_field" );
my $field_frag = $repository->make_element( "span", class=>"ep_problem_field:$name_field" );
$field_frag->appendChild($field_text);
push @problems, $repository->html_phrase( "warnings:orcid_invalid",
orcid => $repository->get_repository->make_text($orcid),
field => $field_frag,
);
}
} else {
$repository->get_repository->log( "Can not call isValidORCID." );
}
}
}
}
</source>

Phrase for "warnings:orcid_invalid":

<source lang="xml">
<epp:phrase id="warnings:orcid_invalid">The ORCID ID: <epc:pin name="orcid"/> is not a valid ORCID ID as it does not conform to the ORCID ID specification. Please edit the <epc:pin name="field"/> with the associated ORCID or remove it from the name completely.</epp:phrase>
</source>

Additional Function that can be placed either at the end of eprints_validate.pl (after the final };) or elsewhere:
<source lang="perl">
############################################
# Function: isValidORCID
# Description: Used to validate ORCID IDs
#
# From: http://support.orcid.org/knowledgebase/articles/116780-structure-of-the-orcid-identifier (Checksum)
#
$c->{validators}->{isValidORCID} = sub {
my $ORCID = $_[0];
#Check for valid length of 19 characters.
my $size = length($ORCID);
if ($size > 19 )
{
return 0;
} else {
#Check actual validity of the ID mathematically.
$ORCID =~ s/\-//g;
my @chars = split(//, $ORCID);
my $total = 0;
for ( my $i=0; $i<15; $i++) {
$total = ($total + $chars[$i]) *2;
}
my $remainder = $total % 11;
my $result = (12 - $remainder) % 11;
return ($chars[15] == ($result==10 ? 'X' : $result))
}
};
</source>

Additionally you will have to define a custom render to add the fields to be displayed in the abstract/summary page.

= Rendering with Bootstrap =

[[File:orcid_bootstrap.png|thumb|left|alt=ORCIDs displaying in the Bootstrap theme|ORCID and Bootstrap]]

In a recent redesign of [http://eprints.whiterose.ac.uk White Rose Research Online] the [https://github.com/eprintsug/bootstrap Bootstrap theme] was used.
The ORCID links are now enhanced with a tooltip and the green icon. There may be examples on the [http://eprints.whiterose.ac.uk/cgi/latest_tool latest 20 additions] page.

== Bootstrap tooltop ==
This block of code finds anything with a class of 'orcid', and adds the green logo to it, and a tooltip that reads 'ORCID: ''orcid-value''', as shown in the image.

The example code below is based on the following rendering of a person who may have an ORCID:
<source lang="html4strict">


Castillo Ortiz, P.J.
<a href="http://orcid.org/0000-0003-4540-1855" target="_blank" class="orcid">
orcid.org/0000-0003-4540-1855
</a>

</source>

== jQuery ==
<source lang="javascript">
// selector used here depends on your rendering. You may want to use something like a[href*='orcid.org/0000-']
jQuery('.orcid').tooltip({
'placement': 'auto',
'title': function(){ return "ORCID: "+ jQuery(this).text()},
}).append('<img src="/images/orcid_16x16.png" alt="" />').find('span').hide();
</source>

== CSS ==
The green colouring is added using the following css, which also makes the background of the tooltip opaque, not semi-transparent as it is by default.
<source lang="css">
.person + .tooltip > .tooltip-inner,
.orcid + .tooltip > .tooltip-inner {
background-color: #A6CE39;
border: 1px solid #000000;
white-space: pre;
max-width: none;
}
.person + .tooltip.in,
.orcid + .tooltip.in {
opacity: 1;
filter: alpha(opacity=100);
}
/* This adds a green dashed line under an author's name when hovered. This helps in big author lists to tie initials and surname together */
.person:hover {border-bottom: 1px dashed #a6ce39;}
.orcid a:hover {
color: #a6ce39;
}
</source>

= OAI-PMH (Experimental) =
'''[[User:Libjlrs]] 2016-09-29 Warning: this is experimental. I hope others will read, understand, question and improve on this before it becomes some form of best practice!'''

Some metadata profiles support attributes that are useful to propagate ORCIDs e.g. RIOXX (see the [[#Exposing_the_ORCID_in_RIOXX]] section above, and the 'rioxxterms:author' section on http://www.rioxx.net/profiles/v2-0-final/ ).

A lot of harvesters use the oai_dc metadata profile when harvesting records. The DC schema doesn't allow attributes on the dc:creator element, so ORCIDs cannot be added in a sensible way to this profile.

The details below create an additional metadata prefix that adds an attribute to the dc:creator field. The original <code>metadataPrefix=oai_dc</code> output remains unchanged. Using <code>metadataPrefix=oai_dc_orcid</code> will add the orcid attribute where available.

Currently there is not an XSD that describes this change, so a harvester that validates the feed may stop when it encounters an ORCID.

This example is based on the <code>EPrints::Plugin::Export::OAI_DC</code> module from EPrints 3.3.10. You may need to tweak it to make it work for you!

File: <code>~/archives/ARCHIVEID/cfg/plugins/EPrints/Plugin/Export/OAI_DC_ORCID.pm</code>
<source lang="perl">
package EPrints::Plugin::Export::OAI_DC_ORCID;

use EPrints::Plugin::Export::OAI_DC;

@ISA = ( "EPrints::Plugin::Export::OAI_DC", "EPrints::Plugin::Export::DC" );

use strict;

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

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

$self->{name} = "Dublin Core - OAI + ORCID Schema";
$self->{accept} = [ 'dataobj/eprint' ];
$self->{visible} = "";
$self->{suffix} = ".xml";
$self->{mimetype} = "text/xml";

$self->{metadataPrefix} = "oai_dc_orcid";
$self->{xmlns} = "http://www.openarchives.org/OAI/2.0/oai_dc/";
$self->{schemaLocation} = "http://www.openarchives.org/OAI/2.0/oai_dc.xsd";

return $self;
}

sub xml_dataobj
{
my( $plugin, $dataobj ) = @_;

my $data = $plugin->convert_dataobj( $dataobj );

my $dc = $plugin->{session}->make_element(
"oai_dc:dc",
"xmlns:oai_dc" => "http://www.openarchives.org/OAI/2.0/oai_dc/",
"xmlns:dc" => "http://purl.org/dc/elements/1.1/",
"xmlns:xsi" => "http://www.w3.org/2001/XMLSchema-instance",
"xsi:schemaLocation" =>
"http://www.openarchives.org/OAI/2.0/oai_dc/ http://www.openarchives.org/OAI/2.0/oai_dc.xsd" );

# turn the list of pairs into XML blocks (indented by 8) and add them
# them to the DC element.
foreach( @{$data} )
{
$dc->appendChild( $plugin->{session}->render_data_element( 8, "dc:".$_->[0], $_->[1], %{$_->[2]} ) );
# produces <key>value</key>
}

return $dc;
}

sub convert_dataobj
{
my( $plugin, $eprint ) = @_;

my $dataset = $eprint->{dataset};

my @dcdata = ();

push @dcdata, $plugin->simple_value( $eprint, title => "title" );

if( $eprint->exists_and_set( "creators" ) )
{
my $creators = $eprint->get_value( "creators" );
foreach my $creator ( @$creators )
{
next if !defined $creator;

# NOTE THIS IS VERY CRUDE, and should be replaced with more elegant methods (possibly from examples elsewhere on this page).
if( defined $creator->{id} && $creator->{id} =~ /0000/ ){
push @dcdata, [ "creator", EPrints::Utils::make_name_string( $creator->{name} ), { 'orcid' => $creator->{id} } ];
} else {
push @dcdata, [ "creator", EPrints::Utils::make_name_string( $creator->{name} ) ];
}
}
}

if( $eprint->exists_and_set( "subjects" ) )
{
my $subjectid;
foreach $subjectid ( @{$eprint->get_value( "subjects" )} )
{
my $subject = EPrints::DataObj::Subject->new( $plugin->{session}, $subjectid );
# avoid problems with bad subjects
next unless( defined $subject );
push @dcdata, [ "subject", EPrints::Utils::tree_to_utf8( $subject->render_description() ) ];
}
}

push @dcdata, $plugin->simple_value( $eprint, abstract => "description" );
push @dcdata, $plugin->simple_value( $eprint, publisher => "publisher" );

if( $eprint->exists_and_set( "editors_name" ) )
{
my $editors = $eprint->get_value( "editors_name" );
if( defined $editors )
{
foreach my $editor ( @{$editors} )
{
push @dcdata, [ "contributor", EPrints::Utils::make_name_string( $editor ) ];
}
}
}
## Date for discovery. For a month/day we don't have, assume 01.
if( $eprint->exists_and_set( "date" ) )
{
my $date = $eprint->get_value( "date" );
if( defined $date )
{
$date =~ s/(-0+)+$//;
push @dcdata, [ "date", $date ];
}
}

if( $eprint->exists_and_set( "type" ) )
{
push @dcdata, [ "type", EPrints::Utils::tree_to_utf8( $eprint->render_value( "type" ) ) ];
}

my $ref = "NonPeerReviewed";
if( $eprint->exists_and_set( "refereed" ) && $eprint->get_value( "refereed" ) eq "TRUE" )
{
$ref = "PeerReviewed";
}
push @dcdata, [ "type", $ref ];

my @documents = $eprint->get_all_documents();
my $mimetypes = $plugin->{session}->get_repository->get_conf( "oai", "mime_types" );
foreach( @documents )
{
my $format = $mimetypes->{$_->get_value("format")};
$format = $_->get_value("format") unless defined $format;
#$format = "application/octet-stream" unless defined $format;
push @dcdata, [ "format", $format ];
push @dcdata, [ "identifier", $_->get_url() ];
}

# Most commonly a DOI or journal link
push @dcdata, $plugin->simple_value( $eprint, official_url => "relation" );

# The citation for this eprint
push @dcdata, [ "identifier",
EPrints::Utils::tree_to_utf8( $eprint->render_citation() ) ];

# The URL of the abstract page
if( $eprint->is_set( "eprintid" ) )
{
push @dcdata, [ "relation", $eprint->get_url() ];
}
# dc.language not handled yet.
# dc.source not handled yet.
# dc.coverage not handled yet.
# dc.rights not handled yet.

return \@dcdata;
}

1;
</source>

ORCID

2016-10-18T13:26:56Z

Alan.stiles@open.ac.uk: /* Field Recommendations */ added suggestions

This page has been created to gather information about how different EPrints repositories have integrated ORCID.
At this time (April 2016) there doesn't seem to be a 'best practice' approach that has been adopted widely - this will hopefully change over time.

==Field Recommendations==
As at 2016-10-18 these are the recommended field names and types as discussed at the Jisc ORCID hack day in London - Alan Stiles, John Salter, Adam Vials Moore, Peter West, Andrew Beeken

===New MetaField Type===
* Type 'orcid' is a subtype of 'id', provides validation and render methods
N.B. Store the 16 digit, hyphen separated value, without the authority (host) details e.g. 'nnnn-nnnn-nnnn-nnnn' (as per the value returned by the ORCID API)

===User Object===
*new field named 'orcid', type 'orcid' to store the value of the ORCID id for that user

====Suggested fields====
*'orcid_auth_code', type text - to hold the long authorisation token returned by the ORCID API at the end of a successful OAuth2 process
*'orcid_granted_permissions', type text - to hold the permissions granted via the ORCID API during the authorisation process
*'orcid_token_expires', type time - to hold the expiry timestamp for the authorisation code above (time now plus expires duration returned by the ORCID API)

===Eprints Contributors (e.g. creators, editors)===
*new sub-field of contributor_orcid (e.g. creator_orcid, editor_orcid) type 'orcid' to store the value of the ORCID id for that contributor

==Previous Discussions==
If you are looking to retrieve publications from the ORCID service, the [http://bazaar.eprints.org/354/ Import from ORCID (Tier 1 API)] Bazaar package, or the [https://github.com/eprintsug/orcidt2 ORCID Tier 2 api framework] are good places to start.

2016-05-20 [[User:Alan.stiles@open.ac.uk|Alan Stiles]] at The Open University is working on a plugin to connect EPrints with ORCID via the Tier 2 Members API to retrieve ORCID ids and synchronise publications and affiliation details.

Some aspects that need to be considered when adopting ORCIDs, and making them available to other systems are:

* storing the ORCID (see: http://support.orcid.org/knowledgebase/articles/116780-structure-of-the-orcid-identifier)
* rendering the ORCID in abstract pages (see [http://support.orcid.org/knowledgebase/articles/116780-structure-of-the-orcid-identifier link above])
* exposing ORCIDs over OAI-PMH metadata profiles e.g. RIOXX

NB The examples below may refer to the 'creators' field - but the same approach could be used to extend other 'person' fields - e.g. contributors.

= Re-using creators.id subfield =

The creators.id field is labelled 'email' by default, but as it's an 'id' type field, it can be used to store ORCIDs.
To re-label the field, a simple addition to a phrase file in <code>archives/ARCHIVEID/cfg/lang/en/phrases/</code> needs to be made:
<source lang="xml">
<epp:phrase id="eprint_fieldname_creators_id">ORCID / Creators email (if known)</epp:phrase>
</source>

== Rendering the ORCID in a citation ==
The rendering of this field then needs to be changed to accommodate an author with an ORCID. The following script adds methods that can be called via the EPScript language:

<source lang="perl">
# add to e.g. ~/archives/ARCHIVEID/cfg/cfg.d/z_add_to_EPrints_Script_Compiled.pl
# Write into EPrints::Script::Compiled package to allow use of function in epscript
{
package EPrints::Script::Compiled;
use strict;

sub run_wrro_people_with_orcids
{
my( $self, $state, $value ) = @_;

my $session = $state->{session};
my $r = $state->{session}->make_doc_fragment;

my $creators = $value->[0];

foreach my $i (0..$#$creators){

my $creator = @$creators[$i];

if( $i > 0 ){
#not first item (or only one item)
if( $i == $#$creators ){
#last item
$r->appendChild( $session->make_text( " and " ) );
} else {
$r->appendChild( $session->make_text( ", " ) );
}
}

my $person_span = $session->make_element( "span", "class" => "person" );
$person_span->appendChild( $session->render_name( $creator->{name} ) );

my $id = $creator->{id};
if( defined $id && $id =~ m/^(?:orcid.org\/)?(\d{4}\-\d{4}\-\d{4}\-\d{3}(?:\d|X))$/ )
{
my $orcid_span = $session->make_element( "span", "class" => "orcid" );

# According to https://orcid.org/trademark-and-id-display-guidelines
# "recommended display is a hyperlinked URI preceded by the iD icon"
# This looks terrible in a citation. Removed for the time being.
#
# my $orcid_link = $session->make_element(
# "a",
# "href" => "http://orcid.org/",
# "target" => "_blank",
# "class" => "orcid-icon"
# );
# $orcid_link->appendChild( $session->make_element(
# "img",
# "src" => "/images/orcid_16x16.png",
# "title" => "ORCID"
# ) );
# $orcid_span->appendChild( $orcid_link );

my $link = $session->make_element(
"a",
"href" => "http://orcid.org/$1",
"target" => "_blank",
);
$link->appendChild( $session->make_text( "orcid.org/$1" ) );

$orcid_span->appendChild( $session->make_text( "(" ) );
$orcid_span->appendChild( $link );
$orcid_span->appendChild( $session->make_text( ")" ) );

$person_span->appendChild( $session->make_text( " " ) );
$person_span->appendChild( $orcid_span );
}
$r->appendChild( $person_span );
}

return [ $r, "XHTML" ];
}

}
# END EPrints::Script::Compiled additions
</source>

You may also want a bit of CSS to style ORCID links
<source lang="css">
/* Add to e.g. ~/archives/ARCHIVEID/cfg/static/style/auto/zzz_orcid.css */
.person:hover {border-bottom: 1px dashed #a6ce39;}
.orcid {}
.orcid a:hover {
color: #a6ce39;
}
.orcid-icon {}
.orcid-icon img { vertical-align: text-bottom; margin: 0 4px 0 2px; }
</source>

And finally, you have to call the new EPScript function from a citation file e.g. <code>archives/ARCHIVEID/cfg/citations/eprint/default.xml</code>
<source lang="xml">

<print expr="wrro_people_with_orcids(creators)" />
</source>

== Exposing the ORCID in RIOXX ==
Based on re-using the creators.id field, this block of code over-writes the default <code>rioxx2_value_author</code> function.
<source lang="perl">
# Add to e.g. ~/archives/ARCHIVEID/cfg/cfg.d/zzz_rioxx2_overwrites.pl
$c->{rioxx2_value_author} = sub {
my( $eprint ) = @_;

my @authors;
for( @{ $eprint->value( "creators" ) } )
{
my $id = $_->{id};
if( defined $id && $id =~ m/^(?:orcid.org\/)?(\d{4}\-\d{4}\-\d{4}\-\d{3}(?:\d|X))$/ )
{
push @authors, {
author => EPrints::Utils::make_name_string( $_->{name} ),
id => "http://orcid.org/$1"
};
} else {
push @authors, {
author => EPrints::Utils::make_name_string( $_->{name} ),
};
}
}

#NB If your corp_creators has DOIs or ISNIs for the entries, a similar method could be used to include these here.
foreach my $corp ( @{ $eprint->value( "corp_creators" ) } )
{
my $entry = {};
$entry->{name} = $corp;
push @authors, { author => $corp };
}

return \@authors;
};

</source>

= Add additional identifiers to creators =
Another approach to storing ORCIDs is to add an additional sub-field to the creator field.
This has been discussed on the Eprints tech list. If you know how to do this, please document it here!

This is how University of Bath has done it. We're getting the ORCID data from another system, so have used a text field to capture it for display. At present there is no special rendering on it, it's just displaying as a number.
<source lang="perl">
{
name => 'creators',
type => 'compound',
multiple => 1,
fields => [
{
sub_name => 'name',
type => 'name',
hide_honourific => 1,
hide_lineage => 1,
family_first => 1,
},
{
sub_name => 'id',
type => 'text',
input_cols => 20,
allow_null => 1,
},
{
sub_name => 'orcid',
type => 'text',
input_cols => 20,
allow_null => 1,
}

],
input_boxes => 4,
},
</source>
This is how University of Pittsburgh has done it:
<source lang="perl">
{
'name' => 'creators',
'type' => 'compound',
'multiple' => 1,
'fields' => [
{
'sub_name' => 'name',
'type' => 'name',
'hide_honourific' => 1,
'hide_lineage' => 1,
'family_first' => 1,
},
{
'sub_name' => 'email',
'type' => 'text',
'input_cols' => 20,
'allow_null' => 1,
},
{
'sub_name' => 'id',
'type' => 'text',
'input_cols' => 20,
'allow_null' => 1,
},
{
'sub_name' => 'orcid',
'type' => 'id',
'input_cols' => 19,
'allow_null' => 1,
},
],
'input_boxes' => 4,
'render_value' => 'custom_render_creators_with_orcid',
},

</source>

==Notes from Pittsburgh:==
(Information courtesy of Brian Gregg - bdgregg@pitt.edu)

We have added some ORCID functionality in our IR System here at the University of Pittsburgh. We however have not “linked” our IR with orcid.org in anyway such as we do not have a lookup user in ORCID or the ability to add publications from ORCID to our IR. The only link is the entering of the ORCID into the system so that it can be displayed.

An example record is available here: [http://d-scholarship.pitt.edu/28114/ http://d-scholarship.pitt.edu/28114/]

# Users have an ORCID field in their profile – user_fields.pl
# Any “Creator” types have an ORCID field added to the workflow – eprint_fields.pl
# We have added ORCID validation adhering to this document: [http://support.orcid.org/knowledgebase/articles/116780-structure-of-the-orcid-identifier] - eprint_validate.pl
# We have added the ORCID to the “lookup” function to populate the ORCID field from any user entries in the database. – cgi/users/lookup/name
# We display the ORCID as such on the input form, where the green icon links out to our own orcid.pitt.edu site, but could be to orcid.org by default.
# We display the ORCID as such on the public display of the record where the ORCID is linked out to orcid.org (see [http://d-scholarship.pitt.edu/28114/ example record])

ORCID Validator - snippet for eprints_validate.pl
<source lang="perl">
# ORCID ID Validator for individuals
# Reference: http://support.orcid.org/knowledgebase/articles/116780-structure-of-the-orcid-identifier
# REGEX: ^\d{4}-\d{4}-\d{4}-(\d{3}X|\d{4})$
#
my @name_fields = qw( creators contributors exhibitors producers conductors lyricists ); #which ever name fields you added 'orcid' to.
foreach my $name_field ( @name_fields )
{
if( $eprint->is_set( $name_field ) )
{
foreach my $creator ( @{ $eprint->value( $name_field ) } )
{
my $orcid = $creator->{orcid};
next unless defined $orcid;
if ($repository->get_repository->can_call ( "validators", "isValidORCID" ) )
{
if (!$repository->get_repository->call( [ "validators", "isValidORCID" ], $orcid ))
{
my $field_text = $repository->html_phrase( "eprint_fieldname_$name_field" );
my $field_frag = $repository->make_element( "span", class=>"ep_problem_field:$name_field" );
$field_frag->appendChild($field_text);
push @problems, $repository->html_phrase( "warnings:orcid_invalid",
orcid => $repository->get_repository->make_text($orcid),
field => $field_frag,
);
}
} else {
$repository->get_repository->log( "Can not call isValidORCID." );
}
}
}
}
</source>

Phrase for "warnings:orcid_invalid":

<source lang="xml">
<epp:phrase id="warnings:orcid_invalid">The ORCID ID: <epc:pin name="orcid"/> is not a valid ORCID ID as it does not conform to the ORCID ID specification. Please edit the <epc:pin name="field"/> with the associated ORCID or remove it from the name completely.</epp:phrase>
</source>

Additional Function that can be placed either at the end of eprints_validate.pl (after the final };) or elsewhere:
<source lang="perl">
############################################
# Function: isValidORCID
# Description: Used to validate ORCID IDs
#
# From: http://support.orcid.org/knowledgebase/articles/116780-structure-of-the-orcid-identifier (Checksum)
#
$c->{validators}->{isValidORCID} = sub {
my $ORCID = $_[0];
#Check for valid length of 19 characters.
my $size = length($ORCID);
if ($size > 19 )
{
return 0;
} else {
#Check actual validity of the ID mathematically.
$ORCID =~ s/\-//g;
my @chars = split(//, $ORCID);
my $total = 0;
for ( my $i=0; $i<15; $i++) {
$total = ($total + $chars[$i]) *2;
}
my $remainder = $total % 11;
my $result = (12 - $remainder) % 11;
return ($chars[15] == ($result==10 ? 'X' : $result))
}
};
</source>

Additionally you will have to define a custom render to add the fields to be displayed in the abstract/summary page.

= Rendering with Bootstrap =

[[File:orcid_bootstrap.png|thumb|left|alt=ORCIDs displaying in the Bootstrap theme|ORCID and Bootstrap]]

In a recent redesign of [http://eprints.whiterose.ac.uk White Rose Research Online] the [https://github.com/eprintsug/bootstrap Bootstrap theme] was used.
The ORCID links are now enhanced with a tooltip and the green icon. There may be examples on the [http://eprints.whiterose.ac.uk/cgi/latest_tool latest 20 additions] page.

== Bootstrap tooltop ==
This block of code finds anything with a class of 'orcid', and adds the green logo to it, and a tooltip that reads 'ORCID: ''orcid-value''', as shown in the image.

The example code below is based on the following rendering of a person who may have an ORCID:
<source lang="html4strict">


Castillo Ortiz, P.J.
<a href="http://orcid.org/0000-0003-4540-1855" target="_blank" class="orcid">
orcid.org/0000-0003-4540-1855
</a>

</source>

== jQuery ==
<source lang="javascript">
// selector used here depends on your rendering. You may want to use something like a[href*='orcid.org/0000-']
jQuery('.orcid').tooltip({
'placement': 'auto',
'title': function(){ return "ORCID: "+ jQuery(this).text()},
}).append('<img src="/images/orcid_16x16.png" alt="" />').find('span').hide();
</source>

== CSS ==
The green colouring is added using the following css, which also makes the background of the tooltip opaque, not semi-transparent as it is by default.
<source lang="css">
.person + .tooltip > .tooltip-inner,
.orcid + .tooltip > .tooltip-inner {
background-color: #A6CE39;
border: 1px solid #000000;
white-space: pre;
max-width: none;
}
.person + .tooltip.in,
.orcid + .tooltip.in {
opacity: 1;
filter: alpha(opacity=100);
}
/* This adds a green dashed line under an author's name when hovered. This helps in big author lists to tie initials and surname together */
.person:hover {border-bottom: 1px dashed #a6ce39;}
.orcid a:hover {
color: #a6ce39;
}
</source>

= OAI-PMH (Experimental) =
'''[[User:Libjlrs]] 2016-09-29 Warning: this is experimental. I hope others will read, understand, question and improve on this before it becomes some form of best practice!'''

Some metadata profiles support attributes that are useful to propagate ORCIDs e.g. RIOXX (see the [[#Exposing_the_ORCID_in_RIOXX]] section above, and the 'rioxxterms:author' section on http://www.rioxx.net/profiles/v2-0-final/ ).

A lot of harvesters use the oai_dc metadata profile when harvesting records. The DC schema doesn't allow attributes on the dc:creator element, so ORCIDs cannot be added in a sensible way to this profile.

The details below create an additional metadata prefix that adds an attribute to the dc:creator field. The original <code>metadataPrefix=oai_dc</code> output remains unchanged. Using <code>metadataPrefix=oai_dc_orcid</code> will add the orcid attribute where available.

Currently there is not an XSD that describes this change, so a harvester that validates the feed may stop when it encounters an ORCID.

This example is based on the <code>EPrints::Plugin::Export::OAI_DC</code> module from EPrints 3.3.10. You may need to tweak it to make it work for you!

File: <code>~/archives/ARCHIVEID/cfg/plugins/EPrints/Plugin/Export/OAI_DC_ORCID.pm</code>
<source lang="perl">
package EPrints::Plugin::Export::OAI_DC_ORCID;

use EPrints::Plugin::Export::OAI_DC;

@ISA = ( "EPrints::Plugin::Export::OAI_DC", "EPrints::Plugin::Export::DC" );

use strict;

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

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

$self->{name} = "Dublin Core - OAI + ORCID Schema";
$self->{accept} = [ 'dataobj/eprint' ];
$self->{visible} = "";
$self->{suffix} = ".xml";
$self->{mimetype} = "text/xml";

$self->{metadataPrefix} = "oai_dc_orcid";
$self->{xmlns} = "http://www.openarchives.org/OAI/2.0/oai_dc/";
$self->{schemaLocation} = "http://www.openarchives.org/OAI/2.0/oai_dc.xsd";

return $self;
}

sub xml_dataobj
{
my( $plugin, $dataobj ) = @_;

my $data = $plugin->convert_dataobj( $dataobj );

my $dc = $plugin->{session}->make_element(
"oai_dc:dc",
"xmlns:oai_dc" => "http://www.openarchives.org/OAI/2.0/oai_dc/",
"xmlns:dc" => "http://purl.org/dc/elements/1.1/",
"xmlns:xsi" => "http://www.w3.org/2001/XMLSchema-instance",
"xsi:schemaLocation" =>
"http://www.openarchives.org/OAI/2.0/oai_dc/ http://www.openarchives.org/OAI/2.0/oai_dc.xsd" );

# turn the list of pairs into XML blocks (indented by 8) and add them
# them to the DC element.
foreach( @{$data} )
{
$dc->appendChild( $plugin->{session}->render_data_element( 8, "dc:".$_->[0], $_->[1], %{$_->[2]} ) );
# produces <key>value</key>
}

return $dc;
}

sub convert_dataobj
{
my( $plugin, $eprint ) = @_;

my $dataset = $eprint->{dataset};

my @dcdata = ();

push @dcdata, $plugin->simple_value( $eprint, title => "title" );

if( $eprint->exists_and_set( "creators" ) )
{
my $creators = $eprint->get_value( "creators" );
foreach my $creator ( @$creators )
{
next if !defined $creator;

# NOTE THIS IS VERY CRUDE, and should be replaced with more elegant methods (possibly from examples elsewhere on this page).
if( defined $creator->{id} && $creator->{id} =~ /0000/ ){
push @dcdata, [ "creator", EPrints::Utils::make_name_string( $creator->{name} ), { 'orcid' => $creator->{id} } ];
} else {
push @dcdata, [ "creator", EPrints::Utils::make_name_string( $creator->{name} ) ];
}
}
}

if( $eprint->exists_and_set( "subjects" ) )
{
my $subjectid;
foreach $subjectid ( @{$eprint->get_value( "subjects" )} )
{
my $subject = EPrints::DataObj::Subject->new( $plugin->{session}, $subjectid );
# avoid problems with bad subjects
next unless( defined $subject );
push @dcdata, [ "subject", EPrints::Utils::tree_to_utf8( $subject->render_description() ) ];
}
}

push @dcdata, $plugin->simple_value( $eprint, abstract => "description" );
push @dcdata, $plugin->simple_value( $eprint, publisher => "publisher" );

if( $eprint->exists_and_set( "editors_name" ) )
{
my $editors = $eprint->get_value( "editors_name" );
if( defined $editors )
{
foreach my $editor ( @{$editors} )
{
push @dcdata, [ "contributor", EPrints::Utils::make_name_string( $editor ) ];
}
}
}
## Date for discovery. For a month/day we don't have, assume 01.
if( $eprint->exists_and_set( "date" ) )
{
my $date = $eprint->get_value( "date" );
if( defined $date )
{
$date =~ s/(-0+)+$//;
push @dcdata, [ "date", $date ];
}
}

if( $eprint->exists_and_set( "type" ) )
{
push @dcdata, [ "type", EPrints::Utils::tree_to_utf8( $eprint->render_value( "type" ) ) ];
}

my $ref = "NonPeerReviewed";
if( $eprint->exists_and_set( "refereed" ) && $eprint->get_value( "refereed" ) eq "TRUE" )
{
$ref = "PeerReviewed";
}
push @dcdata, [ "type", $ref ];

my @documents = $eprint->get_all_documents();
my $mimetypes = $plugin->{session}->get_repository->get_conf( "oai", "mime_types" );
foreach( @documents )
{
my $format = $mimetypes->{$_->get_value("format")};
$format = $_->get_value("format") unless defined $format;
#$format = "application/octet-stream" unless defined $format;
push @dcdata, [ "format", $format ];
push @dcdata, [ "identifier", $_->get_url() ];
}

# Most commonly a DOI or journal link
push @dcdata, $plugin->simple_value( $eprint, official_url => "relation" );

# The citation for this eprint
push @dcdata, [ "identifier",
EPrints::Utils::tree_to_utf8( $eprint->render_citation() ) ];

# The URL of the abstract page
if( $eprint->is_set( "eprintid" ) )
{
push @dcdata, [ "relation", $eprint->get_url() ];
}
# dc.language not handled yet.
# dc.source not handled yet.
# dc.coverage not handled yet.
# dc.rights not handled yet.

return \@dcdata;
}

1;
</source>

ORCID

2016-10-18T13:14:14Z

Alan.stiles@open.ac.uk: /* User Object */

This page has been created to gather information about how different EPrints repositories have integrated ORCID.
At this time (April 2016) there doesn't seem to be a 'best practice' approach that has been adopted widely - this will hopefully change over time.

==Field Recommendations==
As at 2016-10-18 these are the recommended field names and types as discussed at the Jisc ORCID hack day in London - Alan Stiles, John Salter, Adam Vials Moore, Peter West, Andrew Beeken

===User Object===
new field named 'orcid', type 'orcid' which is a subtype of 'id', incorporating render as url methods etc.

===Eprints Contributors (e.g. creators, editors)===

new sub-field of contributor_orcid (e.g. creator_orcid, editor_orcid)

Store the 16 digit, hyphen separated value, without the authority (host) details e.g. 'nnnn-nnnn-nnnn-nnnn'

==Previous Discussions==
If you are looking to retrieve publications from the ORCID service, the [http://bazaar.eprints.org/354/ Import from ORCID (Tier 1 API)] Bazaar package, or the [https://github.com/eprintsug/orcidt2 ORCID Tier 2 api framework] are good places to start.

2016-05-20 [[User:Alan.stiles@open.ac.uk|Alan Stiles]] at The Open University is working on a plugin to connect EPrints with ORCID via the Tier 2 Members API to retrieve ORCID ids and synchronise publications and affiliation details.

Some aspects that need to be considered when adopting ORCIDs, and making them available to other systems are:

* storing the ORCID (see: http://support.orcid.org/knowledgebase/articles/116780-structure-of-the-orcid-identifier)
* rendering the ORCID in abstract pages (see [http://support.orcid.org/knowledgebase/articles/116780-structure-of-the-orcid-identifier link above])
* exposing ORCIDs over OAI-PMH metadata profiles e.g. RIOXX

NB The examples below may refer to the 'creators' field - but the same approach could be used to extend other 'person' fields - e.g. contributors.

= Re-using creators.id subfield =

The creators.id field is labelled 'email' by default, but as it's an 'id' type field, it can be used to store ORCIDs.
To re-label the field, a simple addition to a phrase file in <code>archives/ARCHIVEID/cfg/lang/en/phrases/</code> needs to be made:
<source lang="xml">
<epp:phrase id="eprint_fieldname_creators_id">ORCID / Creators email (if known)</epp:phrase>
</source>

== Rendering the ORCID in a citation ==
The rendering of this field then needs to be changed to accommodate an author with an ORCID. The following script adds methods that can be called via the EPScript language:

<source lang="perl">
# add to e.g. ~/archives/ARCHIVEID/cfg/cfg.d/z_add_to_EPrints_Script_Compiled.pl
# Write into EPrints::Script::Compiled package to allow use of function in epscript
{
package EPrints::Script::Compiled;
use strict;

sub run_wrro_people_with_orcids
{
my( $self, $state, $value ) = @_;

my $session = $state->{session};
my $r = $state->{session}->make_doc_fragment;

my $creators = $value->[0];

foreach my $i (0..$#$creators){

my $creator = @$creators[$i];

if( $i > 0 ){
#not first item (or only one item)
if( $i == $#$creators ){
#last item
$r->appendChild( $session->make_text( " and " ) );
} else {
$r->appendChild( $session->make_text( ", " ) );
}
}

my $person_span = $session->make_element( "span", "class" => "person" );
$person_span->appendChild( $session->render_name( $creator->{name} ) );

my $id = $creator->{id};
if( defined $id && $id =~ m/^(?:orcid.org\/)?(\d{4}\-\d{4}\-\d{4}\-\d{3}(?:\d|X))$/ )
{
my $orcid_span = $session->make_element( "span", "class" => "orcid" );

# According to https://orcid.org/trademark-and-id-display-guidelines
# "recommended display is a hyperlinked URI preceded by the iD icon"
# This looks terrible in a citation. Removed for the time being.
#
# my $orcid_link = $session->make_element(
# "a",
# "href" => "http://orcid.org/",
# "target" => "_blank",
# "class" => "orcid-icon"
# );
# $orcid_link->appendChild( $session->make_element(
# "img",
# "src" => "/images/orcid_16x16.png",
# "title" => "ORCID"
# ) );
# $orcid_span->appendChild( $orcid_link );

my $link = $session->make_element(
"a",
"href" => "http://orcid.org/$1",
"target" => "_blank",
);
$link->appendChild( $session->make_text( "orcid.org/$1" ) );

$orcid_span->appendChild( $session->make_text( "(" ) );
$orcid_span->appendChild( $link );
$orcid_span->appendChild( $session->make_text( ")" ) );

$person_span->appendChild( $session->make_text( " " ) );
$person_span->appendChild( $orcid_span );
}
$r->appendChild( $person_span );
}

return [ $r, "XHTML" ];
}

}
# END EPrints::Script::Compiled additions
</source>

You may also want a bit of CSS to style ORCID links
<source lang="css">
/* Add to e.g. ~/archives/ARCHIVEID/cfg/static/style/auto/zzz_orcid.css */
.person:hover {border-bottom: 1px dashed #a6ce39;}
.orcid {}
.orcid a:hover {
color: #a6ce39;
}
.orcid-icon {}
.orcid-icon img { vertical-align: text-bottom; margin: 0 4px 0 2px; }
</source>

And finally, you have to call the new EPScript function from a citation file e.g. <code>archives/ARCHIVEID/cfg/citations/eprint/default.xml</code>
<source lang="xml">

<print expr="wrro_people_with_orcids(creators)" />
</source>

== Exposing the ORCID in RIOXX ==
Based on re-using the creators.id field, this block of code over-writes the default <code>rioxx2_value_author</code> function.
<source lang="perl">
# Add to e.g. ~/archives/ARCHIVEID/cfg/cfg.d/zzz_rioxx2_overwrites.pl
$c->{rioxx2_value_author} = sub {
my( $eprint ) = @_;

my @authors;
for( @{ $eprint->value( "creators" ) } )
{
my $id = $_->{id};
if( defined $id && $id =~ m/^(?:orcid.org\/)?(\d{4}\-\d{4}\-\d{4}\-\d{3}(?:\d|X))$/ )
{
push @authors, {
author => EPrints::Utils::make_name_string( $_->{name} ),
id => "http://orcid.org/$1"
};
} else {
push @authors, {
author => EPrints::Utils::make_name_string( $_->{name} ),
};
}
}

#NB If your corp_creators has DOIs or ISNIs for the entries, a similar method could be used to include these here.
foreach my $corp ( @{ $eprint->value( "corp_creators" ) } )
{
my $entry = {};
$entry->{name} = $corp;
push @authors, { author => $corp };
}

return \@authors;
};

</source>

= Add additional identifiers to creators =
Another approach to storing ORCIDs is to add an additional sub-field to the creator field.
This has been discussed on the Eprints tech list. If you know how to do this, please document it here!

This is how University of Bath has done it. We're getting the ORCID data from another system, so have used a text field to capture it for display. At present there is no special rendering on it, it's just displaying as a number.
<source lang="perl">
{
name => 'creators',
type => 'compound',
multiple => 1,
fields => [
{
sub_name => 'name',
type => 'name',
hide_honourific => 1,
hide_lineage => 1,
family_first => 1,
},
{
sub_name => 'id',
type => 'text',
input_cols => 20,
allow_null => 1,
},
{
sub_name => 'orcid',
type => 'text',
input_cols => 20,
allow_null => 1,
}

],
input_boxes => 4,
},
</source>
This is how University of Pittsburgh has done it:
<source lang="perl">
{
'name' => 'creators',
'type' => 'compound',
'multiple' => 1,
'fields' => [
{
'sub_name' => 'name',
'type' => 'name',
'hide_honourific' => 1,
'hide_lineage' => 1,
'family_first' => 1,
},
{
'sub_name' => 'email',
'type' => 'text',
'input_cols' => 20,
'allow_null' => 1,
},
{
'sub_name' => 'id',
'type' => 'text',
'input_cols' => 20,
'allow_null' => 1,
},
{
'sub_name' => 'orcid',
'type' => 'id',
'input_cols' => 19,
'allow_null' => 1,
},
],
'input_boxes' => 4,
'render_value' => 'custom_render_creators_with_orcid',
},

</source>

==Notes from Pittsburgh:==
(Information courtesy of Brian Gregg - bdgregg@pitt.edu)

We have added some ORCID functionality in our IR System here at the University of Pittsburgh. We however have not “linked” our IR with orcid.org in anyway such as we do not have a lookup user in ORCID or the ability to add publications from ORCID to our IR. The only link is the entering of the ORCID into the system so that it can be displayed.

An example record is available here: [http://d-scholarship.pitt.edu/28114/ http://d-scholarship.pitt.edu/28114/]

# Users have an ORCID field in their profile – user_fields.pl
# Any “Creator” types have an ORCID field added to the workflow – eprint_fields.pl
# We have added ORCID validation adhering to this document: [http://support.orcid.org/knowledgebase/articles/116780-structure-of-the-orcid-identifier] - eprint_validate.pl
# We have added the ORCID to the “lookup” function to populate the ORCID field from any user entries in the database. – cgi/users/lookup/name
# We display the ORCID as such on the input form, where the green icon links out to our own orcid.pitt.edu site, but could be to orcid.org by default.
# We display the ORCID as such on the public display of the record where the ORCID is linked out to orcid.org (see [http://d-scholarship.pitt.edu/28114/ example record])

ORCID Validator - snippet for eprints_validate.pl
<source lang="perl">
# ORCID ID Validator for individuals
# Reference: http://support.orcid.org/knowledgebase/articles/116780-structure-of-the-orcid-identifier
# REGEX: ^\d{4}-\d{4}-\d{4}-(\d{3}X|\d{4})$
#
my @name_fields = qw( creators contributors exhibitors producers conductors lyricists ); #which ever name fields you added 'orcid' to.
foreach my $name_field ( @name_fields )
{
if( $eprint->is_set( $name_field ) )
{
foreach my $creator ( @{ $eprint->value( $name_field ) } )
{
my $orcid = $creator->{orcid};
next unless defined $orcid;
if ($repository->get_repository->can_call ( "validators", "isValidORCID" ) )
{
if (!$repository->get_repository->call( [ "validators", "isValidORCID" ], $orcid ))
{
my $field_text = $repository->html_phrase( "eprint_fieldname_$name_field" );
my $field_frag = $repository->make_element( "span", class=>"ep_problem_field:$name_field" );
$field_frag->appendChild($field_text);
push @problems, $repository->html_phrase( "warnings:orcid_invalid",
orcid => $repository->get_repository->make_text($orcid),
field => $field_frag,
);
}
} else {
$repository->get_repository->log( "Can not call isValidORCID." );
}
}
}
}
</source>

Phrase for "warnings:orcid_invalid":

<source lang="xml">
<epp:phrase id="warnings:orcid_invalid">The ORCID ID: <epc:pin name="orcid"/> is not a valid ORCID ID as it does not conform to the ORCID ID specification. Please edit the <epc:pin name="field"/> with the associated ORCID or remove it from the name completely.</epp:phrase>
</source>

Additional Function that can be placed either at the end of eprints_validate.pl (after the final };) or elsewhere:
<source lang="perl">
############################################
# Function: isValidORCID
# Description: Used to validate ORCID IDs
#
# From: http://support.orcid.org/knowledgebase/articles/116780-structure-of-the-orcid-identifier (Checksum)
#
$c->{validators}->{isValidORCID} = sub {
my $ORCID = $_[0];
#Check for valid length of 19 characters.
my $size = length($ORCID);
if ($size > 19 )
{
return 0;
} else {
#Check actual validity of the ID mathematically.
$ORCID =~ s/\-//g;
my @chars = split(//, $ORCID);
my $total = 0;
for ( my $i=0; $i<15; $i++) {
$total = ($total + $chars[$i]) *2;
}
my $remainder = $total % 11;
my $result = (12 - $remainder) % 11;
return ($chars[15] == ($result==10 ? 'X' : $result))
}
};
</source>

Additionally you will have to define a custom render to add the fields to be displayed in the abstract/summary page.

= Rendering with Bootstrap =

[[File:orcid_bootstrap.png|thumb|left|alt=ORCIDs displaying in the Bootstrap theme|ORCID and Bootstrap]]

In a recent redesign of [http://eprints.whiterose.ac.uk White Rose Research Online] the [https://github.com/eprintsug/bootstrap Bootstrap theme] was used.
The ORCID links are now enhanced with a tooltip and the green icon. There may be examples on the [http://eprints.whiterose.ac.uk/cgi/latest_tool latest 20 additions] page.

== Bootstrap tooltop ==
This block of code finds anything with a class of 'orcid', and adds the green logo to it, and a tooltip that reads 'ORCID: ''orcid-value''', as shown in the image.

The example code below is based on the following rendering of a person who may have an ORCID:
<source lang="html4strict">


Castillo Ortiz, P.J.
<a href="http://orcid.org/0000-0003-4540-1855" target="_blank" class="orcid">
orcid.org/0000-0003-4540-1855
</a>

</source>

== jQuery ==
<source lang="javascript">
// selector used here depends on your rendering. You may want to use something like a[href*='orcid.org/0000-']
jQuery('.orcid').tooltip({
'placement': 'auto',
'title': function(){ return "ORCID: "+ jQuery(this).text()},
}).append('<img src="/images/orcid_16x16.png" alt="" />').find('span').hide();
</source>

== CSS ==
The green colouring is added using the following css, which also makes the background of the tooltip opaque, not semi-transparent as it is by default.
<source lang="css">
.person + .tooltip > .tooltip-inner,
.orcid + .tooltip > .tooltip-inner {
background-color: #A6CE39;
border: 1px solid #000000;
white-space: pre;
max-width: none;
}
.person + .tooltip.in,
.orcid + .tooltip.in {
opacity: 1;
filter: alpha(opacity=100);
}
/* This adds a green dashed line under an author's name when hovered. This helps in big author lists to tie initials and surname together */
.person:hover {border-bottom: 1px dashed #a6ce39;}
.orcid a:hover {
color: #a6ce39;
}
</source>

= OAI-PMH (Experimental) =
'''[[User:Libjlrs]] 2016-09-29 Warning: this is experimental. I hope others will read, understand, question and improve on this before it becomes some form of best practice!'''

Some metadata profiles support attributes that are useful to propagate ORCIDs e.g. RIOXX (see the [[#Exposing_the_ORCID_in_RIOXX]] section above, and the 'rioxxterms:author' section on http://www.rioxx.net/profiles/v2-0-final/ ).

A lot of harvesters use the oai_dc metadata profile when harvesting records. The DC schema doesn't allow attributes on the dc:creator element, so ORCIDs cannot be added in a sensible way to this profile.

The details below create an additional metadata prefix that adds an attribute to the dc:creator field. The original <code>metadataPrefix=oai_dc</code> output remains unchanged. Using <code>metadataPrefix=oai_dc_orcid</code> will add the orcid attribute where available.

Currently there is not an XSD that describes this change, so a harvester that validates the feed may stop when it encounters an ORCID.

This example is based on the <code>EPrints::Plugin::Export::OAI_DC</code> module from EPrints 3.3.10. You may need to tweak it to make it work for you!

File: <code>~/archives/ARCHIVEID/cfg/plugins/EPrints/Plugin/Export/OAI_DC_ORCID.pm</code>
<source lang="perl">
package EPrints::Plugin::Export::OAI_DC_ORCID;

use EPrints::Plugin::Export::OAI_DC;

@ISA = ( "EPrints::Plugin::Export::OAI_DC", "EPrints::Plugin::Export::DC" );

use strict;

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

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

$self->{name} = "Dublin Core - OAI + ORCID Schema";
$self->{accept} = [ 'dataobj/eprint' ];
$self->{visible} = "";
$self->{suffix} = ".xml";
$self->{mimetype} = "text/xml";

$self->{metadataPrefix} = "oai_dc_orcid";
$self->{xmlns} = "http://www.openarchives.org/OAI/2.0/oai_dc/";
$self->{schemaLocation} = "http://www.openarchives.org/OAI/2.0/oai_dc.xsd";

return $self;
}

sub xml_dataobj
{
my( $plugin, $dataobj ) = @_;

my $data = $plugin->convert_dataobj( $dataobj );

my $dc = $plugin->{session}->make_element(
"oai_dc:dc",
"xmlns:oai_dc" => "http://www.openarchives.org/OAI/2.0/oai_dc/",
"xmlns:dc" => "http://purl.org/dc/elements/1.1/",
"xmlns:xsi" => "http://www.w3.org/2001/XMLSchema-instance",
"xsi:schemaLocation" =>
"http://www.openarchives.org/OAI/2.0/oai_dc/ http://www.openarchives.org/OAI/2.0/oai_dc.xsd" );

# turn the list of pairs into XML blocks (indented by 8) and add them
# them to the DC element.
foreach( @{$data} )
{
$dc->appendChild( $plugin->{session}->render_data_element( 8, "dc:".$_->[0], $_->[1], %{$_->[2]} ) );
# produces <key>value</key>
}

return $dc;
}

sub convert_dataobj
{
my( $plugin, $eprint ) = @_;

my $dataset = $eprint->{dataset};

my @dcdata = ();

push @dcdata, $plugin->simple_value( $eprint, title => "title" );

if( $eprint->exists_and_set( "creators" ) )
{
my $creators = $eprint->get_value( "creators" );
foreach my $creator ( @$creators )
{
next if !defined $creator;

# NOTE THIS IS VERY CRUDE, and should be replaced with more elegant methods (possibly from examples elsewhere on this page).
if( defined $creator->{id} && $creator->{id} =~ /0000/ ){
push @dcdata, [ "creator", EPrints::Utils::make_name_string( $creator->{name} ), { 'orcid' => $creator->{id} } ];
} else {
push @dcdata, [ "creator", EPrints::Utils::make_name_string( $creator->{name} ) ];
}
}
}

if( $eprint->exists_and_set( "subjects" ) )
{
my $subjectid;
foreach $subjectid ( @{$eprint->get_value( "subjects" )} )
{
my $subject = EPrints::DataObj::Subject->new( $plugin->{session}, $subjectid );
# avoid problems with bad subjects
next unless( defined $subject );
push @dcdata, [ "subject", EPrints::Utils::tree_to_utf8( $subject->render_description() ) ];
}
}

push @dcdata, $plugin->simple_value( $eprint, abstract => "description" );
push @dcdata, $plugin->simple_value( $eprint, publisher => "publisher" );

if( $eprint->exists_and_set( "editors_name" ) )
{
my $editors = $eprint->get_value( "editors_name" );
if( defined $editors )
{
foreach my $editor ( @{$editors} )
{
push @dcdata, [ "contributor", EPrints::Utils::make_name_string( $editor ) ];
}
}
}
## Date for discovery. For a month/day we don't have, assume 01.
if( $eprint->exists_and_set( "date" ) )
{
my $date = $eprint->get_value( "date" );
if( defined $date )
{
$date =~ s/(-0+)+$//;
push @dcdata, [ "date", $date ];
}
}

if( $eprint->exists_and_set( "type" ) )
{
push @dcdata, [ "type", EPrints::Utils::tree_to_utf8( $eprint->render_value( "type" ) ) ];
}

my $ref = "NonPeerReviewed";
if( $eprint->exists_and_set( "refereed" ) && $eprint->get_value( "refereed" ) eq "TRUE" )
{
$ref = "PeerReviewed";
}
push @dcdata, [ "type", $ref ];

my @documents = $eprint->get_all_documents();
my $mimetypes = $plugin->{session}->get_repository->get_conf( "oai", "mime_types" );
foreach( @documents )
{
my $format = $mimetypes->{$_->get_value("format")};
$format = $_->get_value("format") unless defined $format;
#$format = "application/octet-stream" unless defined $format;
push @dcdata, [ "format", $format ];
push @dcdata, [ "identifier", $_->get_url() ];
}

# Most commonly a DOI or journal link
push @dcdata, $plugin->simple_value( $eprint, official_url => "relation" );

# The citation for this eprint
push @dcdata, [ "identifier",
EPrints::Utils::tree_to_utf8( $eprint->render_citation() ) ];

# The URL of the abstract page
if( $eprint->is_set( "eprintid" ) )
{
push @dcdata, [ "relation", $eprint->get_url() ];
}
# dc.language not handled yet.
# dc.source not handled yet.
# dc.coverage not handled yet.
# dc.rights not handled yet.

return \@dcdata;
}

1;
</source>

ORCID

2016-10-18T13:12:34Z

Alan.stiles@open.ac.uk: sections

This page has been created to gather information about how different EPrints repositories have integrated ORCID.
At this time (April 2016) there doesn't seem to be a 'best practice' approach that has been adopted widely - this will hopefully change over time.

==Field Recommendations==
As at 2016-10-18 these are the recommended field names and types as discussed at the Jisc ORCID hack day in London - Alan Stiles, John Salter, Adam Vials Moore, Peter West, Andrew Beeken

===User Table===
new field named 'orcid', type 'orcid' which is a subtype of 'id'

===Eprints Contributors (e.g. creators, editors)===

new sub-field of contributor_orcid (e.g. creator_orcid, editor_orcid)

Store the 16 digit, hyphen separated value, without the authority (host) details e.g. 'nnnn-nnnn-nnnn-nnnn'

==Previous Discussions==
If you are looking to retrieve publications from the ORCID service, the [http://bazaar.eprints.org/354/ Import from ORCID (Tier 1 API)] Bazaar package, or the [https://github.com/eprintsug/orcidt2 ORCID Tier 2 api framework] are good places to start.

2016-05-20 [[User:Alan.stiles@open.ac.uk|Alan Stiles]] at The Open University is working on a plugin to connect EPrints with ORCID via the Tier 2 Members API to retrieve ORCID ids and synchronise publications and affiliation details.

Some aspects that need to be considered when adopting ORCIDs, and making them available to other systems are:

* storing the ORCID (see: http://support.orcid.org/knowledgebase/articles/116780-structure-of-the-orcid-identifier)
* rendering the ORCID in abstract pages (see [http://support.orcid.org/knowledgebase/articles/116780-structure-of-the-orcid-identifier link above])
* exposing ORCIDs over OAI-PMH metadata profiles e.g. RIOXX

NB The examples below may refer to the 'creators' field - but the same approach could be used to extend other 'person' fields - e.g. contributors.

= Re-using creators.id subfield =

The creators.id field is labelled 'email' by default, but as it's an 'id' type field, it can be used to store ORCIDs.
To re-label the field, a simple addition to a phrase file in <code>archives/ARCHIVEID/cfg/lang/en/phrases/</code> needs to be made:
<source lang="xml">
<epp:phrase id="eprint_fieldname_creators_id">ORCID / Creators email (if known)</epp:phrase>
</source>

== Rendering the ORCID in a citation ==
The rendering of this field then needs to be changed to accommodate an author with an ORCID. The following script adds methods that can be called via the EPScript language:

<source lang="perl">
# add to e.g. ~/archives/ARCHIVEID/cfg/cfg.d/z_add_to_EPrints_Script_Compiled.pl
# Write into EPrints::Script::Compiled package to allow use of function in epscript
{
package EPrints::Script::Compiled;
use strict;

sub run_wrro_people_with_orcids
{
my( $self, $state, $value ) = @_;

my $session = $state->{session};
my $r = $state->{session}->make_doc_fragment;

my $creators = $value->[0];

foreach my $i (0..$#$creators){

my $creator = @$creators[$i];

if( $i > 0 ){
#not first item (or only one item)
if( $i == $#$creators ){
#last item
$r->appendChild( $session->make_text( " and " ) );
} else {
$r->appendChild( $session->make_text( ", " ) );
}
}

my $person_span = $session->make_element( "span", "class" => "person" );
$person_span->appendChild( $session->render_name( $creator->{name} ) );

my $id = $creator->{id};
if( defined $id && $id =~ m/^(?:orcid.org\/)?(\d{4}\-\d{4}\-\d{4}\-\d{3}(?:\d|X))$/ )
{
my $orcid_span = $session->make_element( "span", "class" => "orcid" );

# According to https://orcid.org/trademark-and-id-display-guidelines
# "recommended display is a hyperlinked URI preceded by the iD icon"
# This looks terrible in a citation. Removed for the time being.
#
# my $orcid_link = $session->make_element(
# "a",
# "href" => "http://orcid.org/",
# "target" => "_blank",
# "class" => "orcid-icon"
# );
# $orcid_link->appendChild( $session->make_element(
# "img",
# "src" => "/images/orcid_16x16.png",
# "title" => "ORCID"
# ) );
# $orcid_span->appendChild( $orcid_link );

my $link = $session->make_element(
"a",
"href" => "http://orcid.org/$1",
"target" => "_blank",
);
$link->appendChild( $session->make_text( "orcid.org/$1" ) );

$orcid_span->appendChild( $session->make_text( "(" ) );
$orcid_span->appendChild( $link );
$orcid_span->appendChild( $session->make_text( ")" ) );

$person_span->appendChild( $session->make_text( " " ) );
$person_span->appendChild( $orcid_span );
}
$r->appendChild( $person_span );
}

return [ $r, "XHTML" ];
}

}
# END EPrints::Script::Compiled additions
</source>

You may also want a bit of CSS to style ORCID links
<source lang="css">
/* Add to e.g. ~/archives/ARCHIVEID/cfg/static/style/auto/zzz_orcid.css */
.person:hover {border-bottom: 1px dashed #a6ce39;}
.orcid {}
.orcid a:hover {
color: #a6ce39;
}
.orcid-icon {}
.orcid-icon img { vertical-align: text-bottom; margin: 0 4px 0 2px; }
</source>

And finally, you have to call the new EPScript function from a citation file e.g. <code>archives/ARCHIVEID/cfg/citations/eprint/default.xml</code>
<source lang="xml">

<print expr="wrro_people_with_orcids(creators)" />
</source>

== Exposing the ORCID in RIOXX ==
Based on re-using the creators.id field, this block of code over-writes the default <code>rioxx2_value_author</code> function.
<source lang="perl">
# Add to e.g. ~/archives/ARCHIVEID/cfg/cfg.d/zzz_rioxx2_overwrites.pl
$c->{rioxx2_value_author} = sub {
my( $eprint ) = @_;

my @authors;
for( @{ $eprint->value( "creators" ) } )
{
my $id = $_->{id};
if( defined $id && $id =~ m/^(?:orcid.org\/)?(\d{4}\-\d{4}\-\d{4}\-\d{3}(?:\d|X))$/ )
{
push @authors, {
author => EPrints::Utils::make_name_string( $_->{name} ),
id => "http://orcid.org/$1"
};
} else {
push @authors, {
author => EPrints::Utils::make_name_string( $_->{name} ),
};
}
}

#NB If your corp_creators has DOIs or ISNIs for the entries, a similar method could be used to include these here.
foreach my $corp ( @{ $eprint->value( "corp_creators" ) } )
{
my $entry = {};
$entry->{name} = $corp;
push @authors, { author => $corp };
}

return \@authors;
};

</source>

= Add additional identifiers to creators =
Another approach to storing ORCIDs is to add an additional sub-field to the creator field.
This has been discussed on the Eprints tech list. If you know how to do this, please document it here!

This is how University of Bath has done it. We're getting the ORCID data from another system, so have used a text field to capture it for display. At present there is no special rendering on it, it's just displaying as a number.
<source lang="perl">
{
name => 'creators',
type => 'compound',
multiple => 1,
fields => [
{
sub_name => 'name',
type => 'name',
hide_honourific => 1,
hide_lineage => 1,
family_first => 1,
},
{
sub_name => 'id',
type => 'text',
input_cols => 20,
allow_null => 1,
},
{
sub_name => 'orcid',
type => 'text',
input_cols => 20,
allow_null => 1,
}

],
input_boxes => 4,
},
</source>
This is how University of Pittsburgh has done it:
<source lang="perl">
{
'name' => 'creators',
'type' => 'compound',
'multiple' => 1,
'fields' => [
{
'sub_name' => 'name',
'type' => 'name',
'hide_honourific' => 1,
'hide_lineage' => 1,
'family_first' => 1,
},
{
'sub_name' => 'email',
'type' => 'text',
'input_cols' => 20,
'allow_null' => 1,
},
{
'sub_name' => 'id',
'type' => 'text',
'input_cols' => 20,
'allow_null' => 1,
},
{
'sub_name' => 'orcid',
'type' => 'id',
'input_cols' => 19,
'allow_null' => 1,
},
],
'input_boxes' => 4,
'render_value' => 'custom_render_creators_with_orcid',
},

</source>

==Notes from Pittsburgh:==
(Information courtesy of Brian Gregg - bdgregg@pitt.edu)

We have added some ORCID functionality in our IR System here at the University of Pittsburgh. We however have not “linked” our IR with orcid.org in anyway such as we do not have a lookup user in ORCID or the ability to add publications from ORCID to our IR. The only link is the entering of the ORCID into the system so that it can be displayed.

An example record is available here: [http://d-scholarship.pitt.edu/28114/ http://d-scholarship.pitt.edu/28114/]

# Users have an ORCID field in their profile – user_fields.pl
# Any “Creator” types have an ORCID field added to the workflow – eprint_fields.pl
# We have added ORCID validation adhering to this document: [http://support.orcid.org/knowledgebase/articles/116780-structure-of-the-orcid-identifier] - eprint_validate.pl
# We have added the ORCID to the “lookup” function to populate the ORCID field from any user entries in the database. – cgi/users/lookup/name
# We display the ORCID as such on the input form, where the green icon links out to our own orcid.pitt.edu site, but could be to orcid.org by default.
# We display the ORCID as such on the public display of the record where the ORCID is linked out to orcid.org (see [http://d-scholarship.pitt.edu/28114/ example record])

ORCID Validator - snippet for eprints_validate.pl
<source lang="perl">
# ORCID ID Validator for individuals
# Reference: http://support.orcid.org/knowledgebase/articles/116780-structure-of-the-orcid-identifier
# REGEX: ^\d{4}-\d{4}-\d{4}-(\d{3}X|\d{4})$
#
my @name_fields = qw( creators contributors exhibitors producers conductors lyricists ); #which ever name fields you added 'orcid' to.
foreach my $name_field ( @name_fields )
{
if( $eprint->is_set( $name_field ) )
{
foreach my $creator ( @{ $eprint->value( $name_field ) } )
{
my $orcid = $creator->{orcid};
next unless defined $orcid;
if ($repository->get_repository->can_call ( "validators", "isValidORCID" ) )
{
if (!$repository->get_repository->call( [ "validators", "isValidORCID" ], $orcid ))
{
my $field_text = $repository->html_phrase( "eprint_fieldname_$name_field" );
my $field_frag = $repository->make_element( "span", class=>"ep_problem_field:$name_field" );
$field_frag->appendChild($field_text);
push @problems, $repository->html_phrase( "warnings:orcid_invalid",
orcid => $repository->get_repository->make_text($orcid),
field => $field_frag,
);
}
} else {
$repository->get_repository->log( "Can not call isValidORCID." );
}
}
}
}
</source>

Phrase for "warnings:orcid_invalid":

<source lang="xml">
<epp:phrase id="warnings:orcid_invalid">The ORCID ID: <epc:pin name="orcid"/> is not a valid ORCID ID as it does not conform to the ORCID ID specification. Please edit the <epc:pin name="field"/> with the associated ORCID or remove it from the name completely.</epp:phrase>
</source>

Additional Function that can be placed either at the end of eprints_validate.pl (after the final };) or elsewhere:
<source lang="perl">
############################################
# Function: isValidORCID
# Description: Used to validate ORCID IDs
#
# From: http://support.orcid.org/knowledgebase/articles/116780-structure-of-the-orcid-identifier (Checksum)
#
$c->{validators}->{isValidORCID} = sub {
my $ORCID = $_[0];
#Check for valid length of 19 characters.
my $size = length($ORCID);
if ($size > 19 )
{
return 0;
} else {
#Check actual validity of the ID mathematically.
$ORCID =~ s/\-//g;
my @chars = split(//, $ORCID);
my $total = 0;
for ( my $i=0; $i<15; $i++) {
$total = ($total + $chars[$i]) *2;
}
my $remainder = $total % 11;
my $result = (12 - $remainder) % 11;
return ($chars[15] == ($result==10 ? 'X' : $result))
}
};
</source>

Additionally you will have to define a custom render to add the fields to be displayed in the abstract/summary page.

= Rendering with Bootstrap =

[[File:orcid_bootstrap.png|thumb|left|alt=ORCIDs displaying in the Bootstrap theme|ORCID and Bootstrap]]

In a recent redesign of [http://eprints.whiterose.ac.uk White Rose Research Online] the [https://github.com/eprintsug/bootstrap Bootstrap theme] was used.
The ORCID links are now enhanced with a tooltip and the green icon. There may be examples on the [http://eprints.whiterose.ac.uk/cgi/latest_tool latest 20 additions] page.

== Bootstrap tooltop ==
This block of code finds anything with a class of 'orcid', and adds the green logo to it, and a tooltip that reads 'ORCID: ''orcid-value''', as shown in the image.

The example code below is based on the following rendering of a person who may have an ORCID:
<source lang="html4strict">


Castillo Ortiz, P.J.
<a href="http://orcid.org/0000-0003-4540-1855" target="_blank" class="orcid">
orcid.org/0000-0003-4540-1855
</a>

</source>

== jQuery ==
<source lang="javascript">
// selector used here depends on your rendering. You may want to use something like a[href*='orcid.org/0000-']
jQuery('.orcid').tooltip({
'placement': 'auto',
'title': function(){ return "ORCID: "+ jQuery(this).text()},
}).append('<img src="/images/orcid_16x16.png" alt="" />').find('span').hide();
</source>

== CSS ==
The green colouring is added using the following css, which also makes the background of the tooltip opaque, not semi-transparent as it is by default.
<source lang="css">
.person + .tooltip > .tooltip-inner,
.orcid + .tooltip > .tooltip-inner {
background-color: #A6CE39;
border: 1px solid #000000;
white-space: pre;
max-width: none;
}
.person + .tooltip.in,
.orcid + .tooltip.in {
opacity: 1;
filter: alpha(opacity=100);
}
/* This adds a green dashed line under an author's name when hovered. This helps in big author lists to tie initials and surname together */
.person:hover {border-bottom: 1px dashed #a6ce39;}
.orcid a:hover {
color: #a6ce39;
}
</source>

= OAI-PMH (Experimental) =
'''[[User:Libjlrs]] 2016-09-29 Warning: this is experimental. I hope others will read, understand, question and improve on this before it becomes some form of best practice!'''

Some metadata profiles support attributes that are useful to propagate ORCIDs e.g. RIOXX (see the [[#Exposing_the_ORCID_in_RIOXX]] section above, and the 'rioxxterms:author' section on http://www.rioxx.net/profiles/v2-0-final/ ).

A lot of harvesters use the oai_dc metadata profile when harvesting records. The DC schema doesn't allow attributes on the dc:creator element, so ORCIDs cannot be added in a sensible way to this profile.

The details below create an additional metadata prefix that adds an attribute to the dc:creator field. The original <code>metadataPrefix=oai_dc</code> output remains unchanged. Using <code>metadataPrefix=oai_dc_orcid</code> will add the orcid attribute where available.

Currently there is not an XSD that describes this change, so a harvester that validates the feed may stop when it encounters an ORCID.

This example is based on the <code>EPrints::Plugin::Export::OAI_DC</code> module from EPrints 3.3.10. You may need to tweak it to make it work for you!

File: <code>~/archives/ARCHIVEID/cfg/plugins/EPrints/Plugin/Export/OAI_DC_ORCID.pm</code>
<source lang="perl">
package EPrints::Plugin::Export::OAI_DC_ORCID;

use EPrints::Plugin::Export::OAI_DC;

@ISA = ( "EPrints::Plugin::Export::OAI_DC", "EPrints::Plugin::Export::DC" );

use strict;

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

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

$self->{name} = "Dublin Core - OAI + ORCID Schema";
$self->{accept} = [ 'dataobj/eprint' ];
$self->{visible} = "";
$self->{suffix} = ".xml";
$self->{mimetype} = "text/xml";

$self->{metadataPrefix} = "oai_dc_orcid";
$self->{xmlns} = "http://www.openarchives.org/OAI/2.0/oai_dc/";
$self->{schemaLocation} = "http://www.openarchives.org/OAI/2.0/oai_dc.xsd";

return $self;
}

sub xml_dataobj
{
my( $plugin, $dataobj ) = @_;

my $data = $plugin->convert_dataobj( $dataobj );

my $dc = $plugin->{session}->make_element(
"oai_dc:dc",
"xmlns:oai_dc" => "http://www.openarchives.org/OAI/2.0/oai_dc/",
"xmlns:dc" => "http://purl.org/dc/elements/1.1/",
"xmlns:xsi" => "http://www.w3.org/2001/XMLSchema-instance",
"xsi:schemaLocation" =>
"http://www.openarchives.org/OAI/2.0/oai_dc/ http://www.openarchives.org/OAI/2.0/oai_dc.xsd" );

# turn the list of pairs into XML blocks (indented by 8) and add them
# them to the DC element.
foreach( @{$data} )
{
$dc->appendChild( $plugin->{session}->render_data_element( 8, "dc:".$_->[0], $_->[1], %{$_->[2]} ) );
# produces <key>value</key>
}

return $dc;
}

sub convert_dataobj
{
my( $plugin, $eprint ) = @_;

my $dataset = $eprint->{dataset};

my @dcdata = ();

push @dcdata, $plugin->simple_value( $eprint, title => "title" );

if( $eprint->exists_and_set( "creators" ) )
{
my $creators = $eprint->get_value( "creators" );
foreach my $creator ( @$creators )
{
next if !defined $creator;

# NOTE THIS IS VERY CRUDE, and should be replaced with more elegant methods (possibly from examples elsewhere on this page).
if( defined $creator->{id} && $creator->{id} =~ /0000/ ){
push @dcdata, [ "creator", EPrints::Utils::make_name_string( $creator->{name} ), { 'orcid' => $creator->{id} } ];
} else {
push @dcdata, [ "creator", EPrints::Utils::make_name_string( $creator->{name} ) ];
}
}
}

if( $eprint->exists_and_set( "subjects" ) )
{
my $subjectid;
foreach $subjectid ( @{$eprint->get_value( "subjects" )} )
{
my $subject = EPrints::DataObj::Subject->new( $plugin->{session}, $subjectid );
# avoid problems with bad subjects
next unless( defined $subject );
push @dcdata, [ "subject", EPrints::Utils::tree_to_utf8( $subject->render_description() ) ];
}
}

push @dcdata, $plugin->simple_value( $eprint, abstract => "description" );
push @dcdata, $plugin->simple_value( $eprint, publisher => "publisher" );

if( $eprint->exists_and_set( "editors_name" ) )
{
my $editors = $eprint->get_value( "editors_name" );
if( defined $editors )
{
foreach my $editor ( @{$editors} )
{
push @dcdata, [ "contributor", EPrints::Utils::make_name_string( $editor ) ];
}
}
}
## Date for discovery. For a month/day we don't have, assume 01.
if( $eprint->exists_and_set( "date" ) )
{
my $date = $eprint->get_value( "date" );
if( defined $date )
{
$date =~ s/(-0+)+$//;
push @dcdata, [ "date", $date ];
}
}

if( $eprint->exists_and_set( "type" ) )
{
push @dcdata, [ "type", EPrints::Utils::tree_to_utf8( $eprint->render_value( "type" ) ) ];
}

my $ref = "NonPeerReviewed";
if( $eprint->exists_and_set( "refereed" ) && $eprint->get_value( "refereed" ) eq "TRUE" )
{
$ref = "PeerReviewed";
}
push @dcdata, [ "type", $ref ];

my @documents = $eprint->get_all_documents();
my $mimetypes = $plugin->{session}->get_repository->get_conf( "oai", "mime_types" );
foreach( @documents )
{
my $format = $mimetypes->{$_->get_value("format")};
$format = $_->get_value("format") unless defined $format;
#$format = "application/octet-stream" unless defined $format;
push @dcdata, [ "format", $format ];
push @dcdata, [ "identifier", $_->get_url() ];
}

# Most commonly a DOI or journal link
push @dcdata, $plugin->simple_value( $eprint, official_url => "relation" );

# The citation for this eprint
push @dcdata, [ "identifier",
EPrints::Utils::tree_to_utf8( $eprint->render_citation() ) ];

# The URL of the abstract page
if( $eprint->is_set( "eprintid" ) )
{
push @dcdata, [ "relation", $eprint->get_url() ];
}
# dc.language not handled yet.
# dc.source not handled yet.
# dc.coverage not handled yet.
# dc.rights not handled yet.

return \@dcdata;
}

1;
</source>

ORCID

2016-10-18T12:14:38Z

Alan.stiles@open.ac.uk: added recommendations for storing ORCID ids

This page has been created to gather information about how different EPrints repositories have integrated ORCID.
At this time (April 2016) there doesn't seem to be a 'best practice' approach that has been adopted widely - this will hopefully change over time.

As at 2016-10-18 these are the recommended field names and types as discussed at the Jisc ORCID hack day in London - Alan Stiles, John Salter, Adam Vials Moore, Peter West, Andrew Beeken

User Table:
new field named 'orcid', type 'orcid' which is a subtype of 'id'

Eprints Contributors (e.g. creators, editors)

new sub-field of contributor_orcid (e.g. creator_orcid, editor_orcid)

Store the 16 digit, hyphen separated value, without the authority (host) details e.g. 'nnnn-nnnn-nnnn-nnnn'

If you are looking to retrieve publications from the ORCID service, the [http://bazaar.eprints.org/354/ Import from ORCID (Tier 1 API)] Bazaar package, or the [https://github.com/eprintsug/orcidt2 ORCID Tier 2 api framework] are good places to start.

2016-05-20 [[User:Alan.stiles@open.ac.uk|Alan Stiles]] at The Open University is working on a plugin to connect EPrints with ORCID via the Tier 2 Members API to retrieve ORCID ids and synchronise publications and affiliation details.

Some aspects that need to be considered when adopting ORCIDs, and making them available to other systems are:

* storing the ORCID (see: http://support.orcid.org/knowledgebase/articles/116780-structure-of-the-orcid-identifier)
* rendering the ORCID in abstract pages (see [http://support.orcid.org/knowledgebase/articles/116780-structure-of-the-orcid-identifier link above])
* exposing ORCIDs over OAI-PMH metadata profiles e.g. RIOXX

NB The examples below may refer to the 'creators' field - but the same approach could be used to extend other 'person' fields - e.g. contributors.

= Re-using creators.id subfield =

The creators.id field is labelled 'email' by default, but as it's an 'id' type field, it can be used to store ORCIDs.
To re-label the field, a simple addition to a phrase file in <code>archives/ARCHIVEID/cfg/lang/en/phrases/</code> needs to be made:
<source lang="xml">
<epp:phrase id="eprint_fieldname_creators_id">ORCID / Creators email (if known)</epp:phrase>
</source>

== Rendering the ORCID in a citation ==
The rendering of this field then needs to be changed to accommodate an author with an ORCID. The following script adds methods that can be called via the EPScript language:

<source lang="perl">
# add to e.g. ~/archives/ARCHIVEID/cfg/cfg.d/z_add_to_EPrints_Script_Compiled.pl
# Write into EPrints::Script::Compiled package to allow use of function in epscript
{
package EPrints::Script::Compiled;
use strict;

sub run_wrro_people_with_orcids
{
my( $self, $state, $value ) = @_;

my $session = $state->{session};
my $r = $state->{session}->make_doc_fragment;

my $creators = $value->[0];

foreach my $i (0..$#$creators){

my $creator = @$creators[$i];

if( $i > 0 ){
#not first item (or only one item)
if( $i == $#$creators ){
#last item
$r->appendChild( $session->make_text( " and " ) );
} else {
$r->appendChild( $session->make_text( ", " ) );
}
}

my $person_span = $session->make_element( "span", "class" => "person" );
$person_span->appendChild( $session->render_name( $creator->{name} ) );

my $id = $creator->{id};
if( defined $id && $id =~ m/^(?:orcid.org\/)?(\d{4}\-\d{4}\-\d{4}\-\d{3}(?:\d|X))$/ )
{
my $orcid_span = $session->make_element( "span", "class" => "orcid" );

# According to https://orcid.org/trademark-and-id-display-guidelines
# "recommended display is a hyperlinked URI preceded by the iD icon"
# This looks terrible in a citation. Removed for the time being.
#
# my $orcid_link = $session->make_element(
# "a",
# "href" => "http://orcid.org/",
# "target" => "_blank",
# "class" => "orcid-icon"
# );
# $orcid_link->appendChild( $session->make_element(
# "img",
# "src" => "/images/orcid_16x16.png",
# "title" => "ORCID"
# ) );
# $orcid_span->appendChild( $orcid_link );

my $link = $session->make_element(
"a",
"href" => "http://orcid.org/$1",
"target" => "_blank",
);
$link->appendChild( $session->make_text( "orcid.org/$1" ) );

$orcid_span->appendChild( $session->make_text( "(" ) );
$orcid_span->appendChild( $link );
$orcid_span->appendChild( $session->make_text( ")" ) );

$person_span->appendChild( $session->make_text( " " ) );
$person_span->appendChild( $orcid_span );
}
$r->appendChild( $person_span );
}

return [ $r, "XHTML" ];
}

}
# END EPrints::Script::Compiled additions
</source>

You may also want a bit of CSS to style ORCID links
<source lang="css">
/* Add to e.g. ~/archives/ARCHIVEID/cfg/static/style/auto/zzz_orcid.css */
.person:hover {border-bottom: 1px dashed #a6ce39;}
.orcid {}
.orcid a:hover {
color: #a6ce39;
}
.orcid-icon {}
.orcid-icon img { vertical-align: text-bottom; margin: 0 4px 0 2px; }
</source>

And finally, you have to call the new EPScript function from a citation file e.g. <code>archives/ARCHIVEID/cfg/citations/eprint/default.xml</code>
<source lang="xml">

<print expr="wrro_people_with_orcids(creators)" />
</source>

== Exposing the ORCID in RIOXX ==
Based on re-using the creators.id field, this block of code over-writes the default <code>rioxx2_value_author</code> function.
<source lang="perl">
# Add to e.g. ~/archives/ARCHIVEID/cfg/cfg.d/zzz_rioxx2_overwrites.pl
$c->{rioxx2_value_author} = sub {
my( $eprint ) = @_;

my @authors;
for( @{ $eprint->value( "creators" ) } )
{
my $id = $_->{id};
if( defined $id && $id =~ m/^(?:orcid.org\/)?(\d{4}\-\d{4}\-\d{4}\-\d{3}(?:\d|X))$/ )
{
push @authors, {
author => EPrints::Utils::make_name_string( $_->{name} ),
id => "http://orcid.org/$1"
};
} else {
push @authors, {
author => EPrints::Utils::make_name_string( $_->{name} ),
};
}
}

#NB If your corp_creators has DOIs or ISNIs for the entries, a similar method could be used to include these here.
foreach my $corp ( @{ $eprint->value( "corp_creators" ) } )
{
my $entry = {};
$entry->{name} = $corp;
push @authors, { author => $corp };
}

return \@authors;
};

</source>

= Add additional identifiers to creators =
Another approach to storing ORCIDs is to add an additional sub-field to the creator field.
This has been discussed on the Eprints tech list. If you know how to do this, please document it here!

This is how University of Bath has done it. We're getting the ORCID data from another system, so have used a text field to capture it for display. At present there is no special rendering on it, it's just displaying as a number.
<source lang="perl">
{
name => 'creators',
type => 'compound',
multiple => 1,
fields => [
{
sub_name => 'name',
type => 'name',
hide_honourific => 1,
hide_lineage => 1,
family_first => 1,
},
{
sub_name => 'id',
type => 'text',
input_cols => 20,
allow_null => 1,
},
{
sub_name => 'orcid',
type => 'text',
input_cols => 20,
allow_null => 1,
}

],
input_boxes => 4,
},
</source>
This is how University of Pittsburgh has done it:
<source lang="perl">
{
'name' => 'creators',
'type' => 'compound',
'multiple' => 1,
'fields' => [
{
'sub_name' => 'name',
'type' => 'name',
'hide_honourific' => 1,
'hide_lineage' => 1,
'family_first' => 1,
},
{
'sub_name' => 'email',
'type' => 'text',
'input_cols' => 20,
'allow_null' => 1,
},
{
'sub_name' => 'id',
'type' => 'text',
'input_cols' => 20,
'allow_null' => 1,
},
{
'sub_name' => 'orcid',
'type' => 'id',
'input_cols' => 19,
'allow_null' => 1,
},
],
'input_boxes' => 4,
'render_value' => 'custom_render_creators_with_orcid',
},

</source>

==Notes from Pittsburgh:==
(Information courtesy of Brian Gregg - bdgregg@pitt.edu)

We have added some ORCID functionality in our IR System here at the University of Pittsburgh. We however have not “linked” our IR with orcid.org in anyway such as we do not have a lookup user in ORCID or the ability to add publications from ORCID to our IR. The only link is the entering of the ORCID into the system so that it can be displayed.

An example record is available here: [http://d-scholarship.pitt.edu/28114/ http://d-scholarship.pitt.edu/28114/]

# Users have an ORCID field in their profile – user_fields.pl
# Any “Creator” types have an ORCID field added to the workflow – eprint_fields.pl
# We have added ORCID validation adhering to this document: [http://support.orcid.org/knowledgebase/articles/116780-structure-of-the-orcid-identifier] - eprint_validate.pl
# We have added the ORCID to the “lookup” function to populate the ORCID field from any user entries in the database. – cgi/users/lookup/name
# We display the ORCID as such on the input form, where the green icon links out to our own orcid.pitt.edu site, but could be to orcid.org by default.
# We display the ORCID as such on the public display of the record where the ORCID is linked out to orcid.org (see [http://d-scholarship.pitt.edu/28114/ example record])

ORCID Validator - snippet for eprints_validate.pl
<source lang="perl">
# ORCID ID Validator for individuals
# Reference: http://support.orcid.org/knowledgebase/articles/116780-structure-of-the-orcid-identifier
# REGEX: ^\d{4}-\d{4}-\d{4}-(\d{3}X|\d{4})$
#
my @name_fields = qw( creators contributors exhibitors producers conductors lyricists ); #which ever name fields you added 'orcid' to.
foreach my $name_field ( @name_fields )
{
if( $eprint->is_set( $name_field ) )
{
foreach my $creator ( @{ $eprint->value( $name_field ) } )
{
my $orcid = $creator->{orcid};
next unless defined $orcid;
if ($repository->get_repository->can_call ( "validators", "isValidORCID" ) )
{
if (!$repository->get_repository->call( [ "validators", "isValidORCID" ], $orcid ))
{
my $field_text = $repository->html_phrase( "eprint_fieldname_$name_field" );
my $field_frag = $repository->make_element( "span", class=>"ep_problem_field:$name_field" );
$field_frag->appendChild($field_text);
push @problems, $repository->html_phrase( "warnings:orcid_invalid",
orcid => $repository->get_repository->make_text($orcid),
field => $field_frag,
);
}
} else {
$repository->get_repository->log( "Can not call isValidORCID." );
}
}
}
}
</source>

Phrase for "warnings:orcid_invalid":

<source lang="xml">
<epp:phrase id="warnings:orcid_invalid">The ORCID ID: <epc:pin name="orcid"/> is not a valid ORCID ID as it does not conform to the ORCID ID specification. Please edit the <epc:pin name="field"/> with the associated ORCID or remove it from the name completely.</epp:phrase>
</source>

Additional Function that can be placed either at the end of eprints_validate.pl (after the final };) or elsewhere:
<source lang="perl">
############################################
# Function: isValidORCID
# Description: Used to validate ORCID IDs
#
# From: http://support.orcid.org/knowledgebase/articles/116780-structure-of-the-orcid-identifier (Checksum)
#
$c->{validators}->{isValidORCID} = sub {
my $ORCID = $_[0];
#Check for valid length of 19 characters.
my $size = length($ORCID);
if ($size > 19 )
{
return 0;
} else {
#Check actual validity of the ID mathematically.
$ORCID =~ s/\-//g;
my @chars = split(//, $ORCID);
my $total = 0;
for ( my $i=0; $i<15; $i++) {
$total = ($total + $chars[$i]) *2;
}
my $remainder = $total % 11;
my $result = (12 - $remainder) % 11;
return ($chars[15] == ($result==10 ? 'X' : $result))
}
};
</source>

Additionally you will have to define a custom render to add the fields to be displayed in the abstract/summary page.

= Rendering with Bootstrap =

[[File:orcid_bootstrap.png|thumb|left|alt=ORCIDs displaying in the Bootstrap theme|ORCID and Bootstrap]]

In a recent redesign of [http://eprints.whiterose.ac.uk White Rose Research Online] the [https://github.com/eprintsug/bootstrap Bootstrap theme] was used.
The ORCID links are now enhanced with a tooltip and the green icon. There may be examples on the [http://eprints.whiterose.ac.uk/cgi/latest_tool latest 20 additions] page.

== Bootstrap tooltop ==
This block of code finds anything with a class of 'orcid', and adds the green logo to it, and a tooltip that reads 'ORCID: ''orcid-value''', as shown in the image.

The example code below is based on the following rendering of a person who may have an ORCID:
<source lang="html4strict">


Castillo Ortiz, P.J.
<a href="http://orcid.org/0000-0003-4540-1855" target="_blank" class="orcid">
orcid.org/0000-0003-4540-1855
</a>

</source>

== jQuery ==
<source lang="javascript">
// selector used here depends on your rendering. You may want to use something like a[href*='orcid.org/0000-']
jQuery('.orcid').tooltip({
'placement': 'auto',
'title': function(){ return "ORCID: "+ jQuery(this).text()},
}).append('<img src="/images/orcid_16x16.png" alt="" />').find('span').hide();
</source>

== CSS ==
The green colouring is added using the following css, which also makes the background of the tooltip opaque, not semi-transparent as it is by default.
<source lang="css">
.person + .tooltip > .tooltip-inner,
.orcid + .tooltip > .tooltip-inner {
background-color: #A6CE39;
border: 1px solid #000000;
white-space: pre;
max-width: none;
}
.person + .tooltip.in,
.orcid + .tooltip.in {
opacity: 1;
filter: alpha(opacity=100);
}
/* This adds a green dashed line under an author's name when hovered. This helps in big author lists to tie initials and surname together */
.person:hover {border-bottom: 1px dashed #a6ce39;}
.orcid a:hover {
color: #a6ce39;
}
</source>

= OAI-PMH (Experimental) =
'''[[User:Libjlrs]] 2016-09-29 Warning: this is experimental. I hope others will read, understand, question and improve on this before it becomes some form of best practice!'''

Some metadata profiles support attributes that are useful to propagate ORCIDs e.g. RIOXX (see the [[#Exposing_the_ORCID_in_RIOXX]] section above, and the 'rioxxterms:author' section on http://www.rioxx.net/profiles/v2-0-final/ ).

A lot of harvesters use the oai_dc metadata profile when harvesting records. The DC schema doesn't allow attributes on the dc:creator element, so ORCIDs cannot be added in a sensible way to this profile.

The details below create an additional metadata prefix that adds an attribute to the dc:creator field. The original <code>metadataPrefix=oai_dc</code> output remains unchanged. Using <code>metadataPrefix=oai_dc_orcid</code> will add the orcid attribute where available.

Currently there is not an XSD that describes this change, so a harvester that validates the feed may stop when it encounters an ORCID.

This example is based on the <code>EPrints::Plugin::Export::OAI_DC</code> module from EPrints 3.3.10. You may need to tweak it to make it work for you!

File: <code>~/archives/ARCHIVEID/cfg/plugins/EPrints/Plugin/Export/OAI_DC_ORCID.pm</code>
<source lang="perl">
package EPrints::Plugin::Export::OAI_DC_ORCID;

use EPrints::Plugin::Export::OAI_DC;

@ISA = ( "EPrints::Plugin::Export::OAI_DC", "EPrints::Plugin::Export::DC" );

use strict;

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

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

$self->{name} = "Dublin Core - OAI + ORCID Schema";
$self->{accept} = [ 'dataobj/eprint' ];
$self->{visible} = "";
$self->{suffix} = ".xml";
$self->{mimetype} = "text/xml";

$self->{metadataPrefix} = "oai_dc_orcid";
$self->{xmlns} = "http://www.openarchives.org/OAI/2.0/oai_dc/";
$self->{schemaLocation} = "http://www.openarchives.org/OAI/2.0/oai_dc.xsd";

return $self;
}

sub xml_dataobj
{
my( $plugin, $dataobj ) = @_;

my $data = $plugin->convert_dataobj( $dataobj );

my $dc = $plugin->{session}->make_element(
"oai_dc:dc",
"xmlns:oai_dc" => "http://www.openarchives.org/OAI/2.0/oai_dc/",
"xmlns:dc" => "http://purl.org/dc/elements/1.1/",
"xmlns:xsi" => "http://www.w3.org/2001/XMLSchema-instance",
"xsi:schemaLocation" =>
"http://www.openarchives.org/OAI/2.0/oai_dc/ http://www.openarchives.org/OAI/2.0/oai_dc.xsd" );

# turn the list of pairs into XML blocks (indented by 8) and add them
# them to the DC element.
foreach( @{$data} )
{
$dc->appendChild( $plugin->{session}->render_data_element( 8, "dc:".$_->[0], $_->[1], %{$_->[2]} ) );
# produces <key>value</key>
}

return $dc;
}

sub convert_dataobj
{
my( $plugin, $eprint ) = @_;

my $dataset = $eprint->{dataset};

my @dcdata = ();

push @dcdata, $plugin->simple_value( $eprint, title => "title" );

if( $eprint->exists_and_set( "creators" ) )
{
my $creators = $eprint->get_value( "creators" );
foreach my $creator ( @$creators )
{
next if !defined $creator;

# NOTE THIS IS VERY CRUDE, and should be replaced with more elegant methods (possibly from examples elsewhere on this page).
if( defined $creator->{id} && $creator->{id} =~ /0000/ ){
push @dcdata, [ "creator", EPrints::Utils::make_name_string( $creator->{name} ), { 'orcid' => $creator->{id} } ];
} else {
push @dcdata, [ "creator", EPrints::Utils::make_name_string( $creator->{name} ) ];
}
}
}

if( $eprint->exists_and_set( "subjects" ) )
{
my $subjectid;
foreach $subjectid ( @{$eprint->get_value( "subjects" )} )
{
my $subject = EPrints::DataObj::Subject->new( $plugin->{session}, $subjectid );
# avoid problems with bad subjects
next unless( defined $subject );
push @dcdata, [ "subject", EPrints::Utils::tree_to_utf8( $subject->render_description() ) ];
}
}

push @dcdata, $plugin->simple_value( $eprint, abstract => "description" );
push @dcdata, $plugin->simple_value( $eprint, publisher => "publisher" );

if( $eprint->exists_and_set( "editors_name" ) )
{
my $editors = $eprint->get_value( "editors_name" );
if( defined $editors )
{
foreach my $editor ( @{$editors} )
{
push @dcdata, [ "contributor", EPrints::Utils::make_name_string( $editor ) ];
}
}
}
## Date for discovery. For a month/day we don't have, assume 01.
if( $eprint->exists_and_set( "date" ) )
{
my $date = $eprint->get_value( "date" );
if( defined $date )
{
$date =~ s/(-0+)+$//;
push @dcdata, [ "date", $date ];
}
}

if( $eprint->exists_and_set( "type" ) )
{
push @dcdata, [ "type", EPrints::Utils::tree_to_utf8( $eprint->render_value( "type" ) ) ];
}

my $ref = "NonPeerReviewed";
if( $eprint->exists_and_set( "refereed" ) && $eprint->get_value( "refereed" ) eq "TRUE" )
{
$ref = "PeerReviewed";
}
push @dcdata, [ "type", $ref ];

my @documents = $eprint->get_all_documents();
my $mimetypes = $plugin->{session}->get_repository->get_conf( "oai", "mime_types" );
foreach( @documents )
{
my $format = $mimetypes->{$_->get_value("format")};
$format = $_->get_value("format") unless defined $format;
#$format = "application/octet-stream" unless defined $format;
push @dcdata, [ "format", $format ];
push @dcdata, [ "identifier", $_->get_url() ];
}

# Most commonly a DOI or journal link
push @dcdata, $plugin->simple_value( $eprint, official_url => "relation" );

# The citation for this eprint
push @dcdata, [ "identifier",
EPrints::Utils::tree_to_utf8( $eprint->render_citation() ) ];

# The URL of the abstract page
if( $eprint->is_set( "eprintid" ) )
{
push @dcdata, [ "relation", $eprint->get_url() ];
}
# dc.language not handled yet.
# dc.source not handled yet.
# dc.coverage not handled yet.
# dc.rights not handled yet.

return \@dcdata;
}

1;
</source>

Installing EPrints on RHEL/Fedora/CentOS

2016-10-14T13:46:07Z

Alan.stiles@open.ac.uk: /* SELinux */ added SELinux network permission

[[Category:Installation]]

==Requirements==

* RedHat Enterprise/CentOS 7 (earlier versions may work)

==Installing==

Add the rpm.eprints.org repository key:

rpm -ivh http://rpm.eprints.org/rpm-eprints-org-key-1-1.noarch.rpm

... the rpm.eprints.org EPrints repository:

rpm -ivh http://rpm.eprints.org/eprints/noarch/rpm-eprints-org-1-1.noarch.rpm

... on '''RHEL 5.x only''' the rpm.eprints.org RHEL updates repository:

rpm -ivh http://rpm.eprints.org/RHEL/5Server/noarch/rpm-eprints-org-RHEL-5-1.noarch.rpm

... on '''RHEL 6.x only''' install antiword if installing EPrints 3.2.x or earlier (from 3.3 onwards only used to as a Word -> PDF converter so not strictly necessary):

rpm -ivh http://rpm.eprints.org/RHEL/5/i386/antiword-0.37-1.i386.rpm
# or for 64 bit:
rpm -ivh http://rpm.eprints.org/RHEL/5/x86_64/antiword-0.37-1.x86_64.rpm

Upgrade your XML libraries:

yum upgrade libxml2 libxslt perl-XML-LibXML perl-XML-LibXSLT

Install EPrints 3:

yum install eprints # 3.3.x and later
yum install eprints3 # 3.2.x

===Other sources for dependencies===

The following RPM repositories may be useful for finding other dependencies required by EPrints that aren't part of the core RHEL system.

http://fedoraproject.org/wiki/EPEL - Fedora Extras for RHEL.

http://pkgs.repoforge.org/rpmforge-release/ - RPMforge, which covers a very large range of Perl modules plus others.

[http://www.imagemagick.org/script/binary-releases.php ImageMagick] provide an RPM for RHEL/CentOS 5. At time of writing the RPM requires fftw3, fltk, jasper and openexr which are available from ''RPMForge''. libwebp is available from [http://rpm.eprints.org/RHEL/5/ rpm.eprints.org].

==SELinux==

If you're using SELinux on your server you will need to give Apache read/write access to the documents directory for all repositories you create and the eprints var folder (indexer log, ticker files):

chcon -R -h -t httpd_sys_script_rw_t /usr/share/eprints/archives/[repoid]/documents/
chcon -R -h -t httpd_sys_script_rw_t /usr/share/eprints/var/

you may also need to tell SELinux to allow apache to talk on the network (maybe only if your database is on a separate server

setsebool -P httpd_can_network_connect=1

==Getting Started==

[[Getting Started with EPrints 3]]

== Troubleshooting ==

=== Failed to parse XML file ===

When installing EPrints on RHEL6 (may apply to other versions), If you get the error:
Failed to parse XML file:
/usr/share/eprints/lib/lang/en/phrases/system.xml: Entity: line 396: parser error : Entity 'nbsp' not defined age or title page. If there are more...

Run
sed -i 's/'''&'''nbsp;/ /g' /usr/share/eprints/lib/lang/en/phrases/system.xml

then navigate to the root of your EPrints install (/opt/eprints or /usr/share/eprints) and run
bin/generate_views *repository_id*
bin/epadmin reload *repository_id*

=== Upgrade from previous 3.3 ===
After a upgrading from previous 3.3, your existing repository's database may need updating.
bin/epadmin update [arcid]

Training Video:Staff Search

2016-06-15T16:01:08Z

Alan.stiles@open.ac.uk: /* Index */

[[Category:Howto]]
[[Category:Training_Video|Staff Search]]

==Introduction==

An overview of the staff search, which allows an editor or an administrator to search for items by item ID, username of depositor and all advanced search fields, regardless of its location in the repository.

==What You Will Learn==

* How to search for items as a staff member

==What You Should Already Know==

* How to log into EPrints

==Resources==

=== Video===
The Video can be found at [http://youtu.be/nc6sZDkc5jI http://youtu.be/nc6sZDkc5jI].
====Index====
* [http://youtu.be/nc6sZDkc5jI?t=0m0s 0:00 introduction]
* [http://youtu.be/nc6sZDkc5jI?t=0m13s 0:13 log in as admin]
* [http://youtu.be/nc6sZDkc5jI?t=0m200s 0:20 open staff search]
* [http://youtu.be/nc6sZDkc5jI?t=0m50s 0:50 search for articles]
* [http://youtu.be/nc6sZDkc5jI?t=1m15s 1:15 search by item id]
* [http://youtu.be/nc6sZDkc5jI?t=1m25s 1:25 explaining other search options]

==== The Video====
<youtube>nc6sZDkc5jI</youtube>

====Notes, Errata and Additional Information====

See [[Search.pl#Adding_fields_to_the_staff_search]] for info about pushing more fields into the staff search.

* EPrints 3.3.15

==Test Yourself==

* Search for an item in a user work area.
* Search for a retired item.
* Search for an item with a particular eprint ID.
* Search for an item belonging to a particular user.

==More Reading==

Training Video:Staff Search

2016-06-15T15:30:15Z

Alan.stiles@open.ac.uk: /* Index */ made index into links

[[Category:Howto]]
[[Category:Training_Video|Staff Search]]

==Introduction==

An overview of the staff search, which allows an editor or an administrator to search for items by item ID, username of depositor and all advanced search fields, regardless of its location in the repository.

==What You Will Learn==

* How to search for items as a staff member

==What You Should Already Know==

* How to log into EPrints

==Resources==

=== Video===
The Video can be found at [http://youtu.be/KzrS_u-4eoM http://youtu.be/KzrS_u-4eoM].
====Index====
* [http://youtu.be/KzrS_u-4eoM?t=0m0s 0:00 introduction]
* [http://youtu.be/KzrS_u-4eoM?t=0m13s 0:13 log in as admin]
* [http://youtu.be/KzrS_u-4eoM?t=0m200s 0:20 open staff search]
* [http://youtu.be/KzrS_u-4eoM?t=0m50s 0:50 search for articles]
* [http://youtu.be/KzrS_u-4eoM?t=1m15s 1:15 search by item id]
* [http://youtu.be/KzrS_u-4eoM?t=1m25s 1:25 explaining other search options]

==== The Video====
<youtube></youtube>

====Notes, Errata and Additional Information====

Any notes, version information, errata, etc concerned with this video

* EPrints 3.3.15

==Test Yourself==

* Search for an item in a user work area.
* Search for a retired item.
* Search for an item with a particular eprint ID.
* Search for an item belonging to a particular user.

==More Reading==

Training Video:Staff Search

2016-06-15T15:19:29Z

Alan.stiles@open.ac.uk: /* Index */ bullet listed

[[Category:Howto]]
[[Category:Training_Video|Staff Search]]

==Introduction==

An overview of the staff search, which allows an editor or an administrator to search for items by item ID, username of depositor and all advanced search fields, regardless of its location in the repository.

==What You Will Learn==

* How to search for items as a staff member

==What You Should Already Know==

* How to log into EPrints

==Resources==

=== Video===
The Video can be found at [http://youtu.be/KzrS_u-4eoM http://youtu.be/KzrS_u-4eoM].
====Index====
* 0:00 introduction
* 0:13 log in as admin
* 0:20 open staff search
* 0:50 search for articles
* 1:15 search by item id
* 1:25 explaining other search options

==== The Video====
<youtube></youtube>

====Notes, Errata and Additional Information====

Any notes, version information, errata, etc concerned with this video

* EPrints 3.3.15

==Test Yourself==

* Search for an item in a user work area.
* Search for a retired item.
* Search for an item with a particular eprint ID.
* Search for an item belonging to a particular user.

==More Reading==

Training Video:Staff Search

2016-06-15T15:17:56Z

Alan.stiles@open.ac.uk: /* Index */ added index details

[[Category:Howto]]
[[Category:Training_Video|Staff Search]]

==Introduction==

An overview of the staff search, which allows an editor or an administrator to search for items by item ID, username of depositor and all advanced search fields, regardless of its location in the repository.

==What You Will Learn==

* How to search for items as a staff member

==What You Should Already Know==

* How to log into EPrints

==Resources==

=== Video===
The Video can be found at [http://youtu.be/KzrS_u-4eoM http://youtu.be/KzrS_u-4eoM].
====Index====
0:00 introduction
0:13 log in as admin
0:20 open staff search
0:50 search for articles
1:15 search by item id
1:25 explain other search options

==== The Video====
<youtube></youtube>

====Notes, Errata and Additional Information====

Any notes, version information, errata, etc concerned with this video

* EPrints 3.3.15

==Test Yourself==

* Search for an item in a user work area.
* Search for a retired item.
* Search for an item with a particular eprint ID.
* Search for an item belonging to a particular user.

==More Reading==

Accessing Metdata Fields

2016-06-03T13:37:41Z

Alan.stiles@open.ac.uk: redirect to corrected typo page

#REDIRECT [[Accessing Metadata Fields]]

Accessing Metadata Fields

2016-06-03T13:36:46Z

Alan.stiles@open.ac.uk: Corrected page title typo from Accessing_Metdata_Fields

{{API}}
[[Category:API]]

This page proves an overview of the API calls you can use to access the data in a DataObj. The example framing this is that of an export plugin.

== The Plugin ==

Below is a very simple export plugin, which outputs a single eprint or list of eprints as Text citations. This can be found in the perl_lib/EPrints/Plugin/Export directory. A good starting place to understand the structure of these plugins is to have a browse through the existing code base.

<pre>
package EPrints::Plugin::Export::Text;

use EPrints::Plugin::Export::TextFile;

@ISA = ( "EPrints::Plugin::Export::TextFile" );

use strict;

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

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

$self->{name} = "ASCII Citation";
$self->{accept} = [ 'dataobj/eprint', 'list/eprint' ];
$self->{visible} = "all";

return $self;
}

sub output_dataobj
{
my( $plugin, $dataobj ) = @_;

my $cite = $dataobj->render_citation;

return EPrints::Utils::tree_to_utf8( $cite )."\n\n";
}

1;
</pre>

Note the output_dataobj function. In an export plugin, this will be called on every item in the list that is being exported, and the results for all items concatenated and outputted.

There are two function calls of particular interest that aid in retrieving and managing data:

<pre>
my $cite = $dataobj->render_citation;
</pre>

This returns an HTML DOM object containing the citation of the dataobj as specified in the configuration files (see cfg/citations/eprint/default.xml). Given an HTML DOM object, the following call will convert it into a string:

<pre>
my $text = EPrints::Utils::tree_to_utf8( $html_dom )
</pre>

== Accessing the DataObjs ==

Every export plugin needs one of two functions. In the case above, where data is extracted from every item and concatenated, output_dataobj needs to be defined. This function will be run on ever dataobj in the list being exported. See the example above.

However, it may be the case that you need to do one of the following:

*output a header
*count the number of records you're exporting
*aggregate data across records

In this case, a output_list function needs to be created. The example below is from the MultilineCSV export plugin:

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

my $part = csv( $plugin->header_row( %opts ) );

my $r = [];

binmode( $opts{fh}, ":utf8" );

if( defined $opts{fh} )
{
print {$opts{fh}} $part;
}
else
{
push @{$r}, $part;
}

# list of things

$opts{list}->map( sub {
my( $session, $dataset, $item ) = @_;

my $part = $plugin->output_dataobj( $item, %opts );
if( defined $opts{fh} )
{
print {$opts{fh}} $part;
}
else
{
push @{$r}, $part;
}
} );

return if( defined $opts{fh} );

return join( '', @{$r} );
}
</pre>

This function outputs a header row for the CSV file and then maps a function on to the list which simply calls the output_dataobj function on each item in the list.

Mapping a function onto a list of objects is the correct way to process the dataobjs.

== Accessing DataObj Metadata ==

A number of functions exist to aid in accessing and rendering values in a dataobj.

<pre>
my $title = $dataobj->value('title');
</pre>

$title will now be a scalar containing the value stored in the title field of the dataobj. A function is provided to enable testing first:

<pre>
if ($dataobj->is_set('title'))
{
$title = $dataobj->value('title');
}
</pre>

It is also possible to find out the fields that an item does have by querying the item's dataset:

<pre>
my $ds = $dataobj->dataset;
my @fields = $ds->fields;
my $fieldvalues;
foreach my $field (@fields)
{
my $fieldname = $field->name;
if ($dataobj->is_set($fieldname))
{
$fieldvalues{$fieldname} = $dataobj->value($fieldname);
}
}
</pre>

== The Structure of Values ==

On an eprint, the title is generally a simple metadata field. When $dataobj->value is called, it returns a scalar value.

EPrints has two types of metadata field:

* Simple
* Compound

Both types can either be a single or multiple values. An example of a compound multiple field is the creators field:

<pre>
my $creators = $dataobj->value('creators');
use Data::Dumper;
print Dumper $creators;
</pre>

Data::Dumper is a very useful library that will output the Perl data structure. In the above case, the output may look something like this:

<pre>
$VAR1 = [
{
'name' => {
'lineage' => '',
'given' => 'Noura',
'honourific' => '',
'family' => 'Abbas'
},
'id' => '10363'
},
{
'name' => {
'lineage' => '',
'given' => 'Andrew',
'honourific' => '',
'family' => 'Gravell'
},
'id' => '22'
},
{
'name' => {
'lineage' => '',
'given' => 'Gary',
'honourific' => '',
'family' => 'Wills'
},
'id' => '395'
}
];
</pre>

The above output shows an array of hashes. The structure can be compared to the configuration of the creators field (see cfg/cfg.d/eprint_fields.pl):

<pre>
{
'name' => 'creators',
'type' => 'compound',
'multiple' => 1,
'fields' => [
{
'sub_name' => 'name',
'type' => 'name',
'hide_honourific' => 1,
'hide_lineage' => 1,
'family_first' => 1,
},
{
'sub_name' => 'id',
'type' => 'text',
'input_cols' => 20,
'allow_null' => 1,
}
],
'input_boxes' => 4,
},
</pre>

Each element in the array consists of a hash that has a key for each sub field of the creator field. Note the structure of the name part of the data dump. The name datatype is also a hash.

To summarise:

<dl>
<dt>Simple
<dd>Usually a scalar value (though some datatypes return a hashref
<dt>Compound
<dd>A hashref containing a simple value for each subfield
<dt>Multiple
<dd>An arrayref containing simple or compound metadata fields
</dl>

The perl 'ref' function can help you to identify the shape of your data.

== Rendering a Field ==

If you just want a sensible text value from a metadata field, the following will usually be enough:

<pre>
my $text = EPrints::Utils::tree_to_utf8( $dataobj->render_value('creators') );
</pre>

This will call the default render method for the field, and convert the HTML DOM object to text.

You can also render a subfield:

<pre>
my $text = EPrints::Utils::tree_to_utf8( $dataobj->render_value('creators_name') );
</pre>

== Documents ==

To get an array of all of the documents attached to an eprint:

<pre>
my @docs = $dataobj->get_all_documents;
</pre>

Note that documents are also first class objects, so document metadata fields can be accessed in the same way as eprint metadata fields. In addition to the above, the following are useful for documents:

<pre>
my $size = 'medium'; #could also be 'small' or 'preview'
my $icon_url = $doc->icon_url(size => $size);
</pre>

<pre>
my $download_url = $doc->get_url;
</pre>

And if you want to access the document on the local storage (though it's important not to modify it):

<pre>
my $path = $doc->local_path
</pre>

... though note that there may be more than one file in that directory (and documents contain files, which are also first class objects).

API:DataObj 101

2016-06-03T13:35:24Z

Alan.stiles@open.ac.uk: correct Typo

#REDIRECT [[Accessing Metadata Fields]]

User:Alan.stiles@open.ac.uk

2016-05-25T15:16:45Z

Alan.stiles@open.ac.uk:

Developer at The Open University focussing on EPrints development of [[http://oro.open.ac.uk "Open Research Online"]]

25/05/2016: Current focus is on developing a plugin to enable communication between EPrints software and ORCID API to retrieve ORCID ids and synchronise publications and affiliation metadata.

User:Alan.stiles@open.ac.uk

2016-05-25T15:16:33Z

Alan.stiles@open.ac.uk:

Developer at The Open University focussing on EPrints development of [[http://oro.open.ac.uk "Open Research Online"]]
25/05/2016: Current focus is on developing a plugin to enable communication between EPrints software and ORCID API to retrieve ORCID ids and synchronise publications and affiliation metadata.

ORCID

2016-05-25T15:14:35Z

Alan.stiles@open.ac.uk: added information about current ORCID plugin development

User:Alan.stiles@open.ac.uk

2016-05-25T15:08:37Z

Alan.stiles@open.ac.uk: Created page with "Developer at The Open University focussing on EPrints development of http://oro.open.ac.uk "Open Research Online""

Developer at The Open University focussing on EPrints development of [[http://oro.open.ac.uk "Open Research Online"]]

Sending user messages

2016-05-17T15:18:30Z

Alan.stiles@open.ac.uk: added an eprints version section

== Tested in EPrints versions ==
3.3.10 - 2016-05-17

==Why==
When you execute a job asynchronously (e.g. as a timed event) you may wish to inform the user of the job's completion. You may also wish to warn the user should something not be configured correctly or if the job failed.
This could either be achieved by sending the user an email (Assuming you have an email address) or by sending them a message within EPrints.

There are 2 places I have encountered user messages thus far - within Plugin Screen actions and from a CGI script. The method for each is similar but not the same. Both require:
a type of message
*message - informational/positive (default coloured green)
*warning - alert to some non-critical issue (default coloured orange)
*error - alert to something critical, like a communications error

a message body, as a DOM object. This could be via $self->{repository}->make_text("Some Text") or a call to a defined phrase within the repository.

==Screen plugin action==
within a screen plugin action, you can send a message to the current user with via the screen processor:

<source lang="perl">
sub action_screen_action
{
my ( $self ) = @_;
$self->{processor}->add_message(
"error", #message type - one of 'message', 'warning' or 'error'
$self->{repository}->make_text("No EPrint found with ID: $eprint_id"), # the body of the message as a DOM object
);
}
</source>

==CGI Script (and other non-screen functions)==
From a CGI script, you can send a message to a user via the repository object, as such you need to specify the user, which need not be the current user:

<source lang="perl">
my $repository = new EPrints::Session;
my $db = $repository->database;
my $current_user = $repository->current_user();
$db->save_user_message(
$current_user->get_value( "userid" ), #Userid to receive the message
"message", #Message type
$repo->html_phrase("some_phrase_identifier", ( #the message body, in this instance a phrase identifier
"name" => $current_user->render_value( "name" ) # pin name/value pairs as required for the phrase;
)
)
);
</source>

[[Category:Snippets]]

Sending user messages

2016-05-17T15:14:36Z

Alan.stiles@open.ac.uk: Created page with "==Why== When you execute a job asynchronously (e.g. as a timed event) you may wish to inform the user of the job's completion. You may also wish to warn the user should somet..."

==Why==
When you execute a job asynchronously (e.g. as a timed event) you may wish to inform the user of the job's completion. You may also wish to warn the user should something not be configured correctly or if the job failed.
This could either be achieved by sending the user an email (Assuming you have an email address) or by sending them a message within EPrints.

There are 2 places I have encountered user messages thus far - within Plugin Screen actions and from a CGI script. The method for each is similar but not the same. Both require:
a type of message
*message - informational/positive (default coloured green)
*warning - alert to some non-critical issue (default coloured orange)
*error - alert to something critical, like a communications error

a message body, as a DOM object. This could be via $self->{repository}->make_text("Some Text") or a call to a defined phrase within the repository.

==Screen plugin action==
within a screen plugin action, you can send a message to the current user with via the screen processor:

<source lang="perl">
sub action_screen_action
{
my ( $self ) = @_;
$self->{processor}->add_message(
"error", #message type - one of 'message', 'warning' or 'error'
$self->{repository}->make_text("No EPrint found with ID: $eprint_id"), # the body of the message as a DOM object
);
}
</source>

==CGI Script (and other non-screen functions)==
From a CGI script, you can send a message to a user via the repository object, as such you need to specify the user, which need not be the current user:

<source lang="perl">
my $repository = new EPrints::Session;
my $db = $repository->database;
my $current_user = $repository->current_user();
$db->save_user_message(
$current_user->get_value( "userid" ), #Userid to receive the message
"message", #Message type
$repo->html_phrase("some_phrase_identifier", ( #the message body, in this instance a phrase identifier
"name" => $current_user->render_value( "name" ) # pin name/value pairs as required for the phrase;
)
)
);
</source>

[[Category:Snippets]]

Community Developments

2016-05-13T13:45:41Z

Alan.stiles@open.ac.uk:

'''-=XXX This page needs tidying and templating XXX=-'''

List here the details of any developments you are currently working on, and whether they might be more widely shared by the community (e.g. a plugin) to try and reduce duplication of effort.

If you have ideas for things to be developed, add them to the [[wishlist]]

*[[ORCID connector]] - obtain ORCIDs and authorisation codes to allow update of publications lists on ORCID system. Should ultimately be a bazaar plugin - Alan Stiles, Open University

Wishlist

2016-05-13T13:43:03Z

Alan.stiles@open.ac.uk: Created page with "(just an e.g. for the page) * It would be great if we could have a common standard for funders details - EPrints User Group discussion 13 May 2016"

(just an e.g. for the page)

* It would be great if we could have a common standard for funders details - EPrints User Group discussion 13 May 2016

Community Developments

2016-05-13T13:40:31Z

Alan.stiles@open.ac.uk:

List here the details of any developments you are currently working on, and whether they might be more widely shared by the community (e.g. a plugin) to try and reduce duplication of effort.

If you have ideas for things to be developed, add them to the [[wishlist]]

*ORCID connector - obtain ORCIDs and authorisation codes to allow update of publications lists on ORCID system. Should ultimately be a bazaar plugin - Alan Stiles, Open University

Community Developments

2016-05-13T13:38:34Z

Alan.stiles@open.ac.uk: Created page with "List here the details of any developments you are currently working on, and whether they might be more widely shared by the community (e.g. a plugin) to try and reduce duplica..."

List here the details of any developments you are currently working on, and whether they might be more widely shared by the community (e.g. a plugin) to try and reduce duplication of effort.

If you have ideas for things to be developed, add them to the wishlist (create a link and page)

*ORCID connector - obtain ORCIDs and authorisation codes to allow update of publications lists on ORCID system. Should ultimately be a bazaar plugin - Alan Stiles, Open University

How to make a Screen perform Actions

2016-05-11T09:06:06Z

Alan.stiles@open.ac.uk: /* Where to go after the action completes */ Added details about redirecting to an absolute url and changed pre tags to source tags on this section

[[Category:Howto]][[Category:Plugins]]

Works in EPrints 3.2+

Please read the page on [[How_to_make_a_Screen_for_the_Admin_Section]] as this extends that information.

NOTE: in this page, $s is the ''session'' or ''repository'' object, and $f is the (x)html DOM fragment

The action buttons are the functionality that make the work... well, flow.

You need to define the "screen" (perl package) that contains the actions, and what the actions are.

===What's happening===

The process has four parts:
# Register the ''actions'' with the EPrints system
# Some ''action'' buttons
# Some ''action'' routines
## A ''allow'' routine
## An ''action'' routine
### These routines could all be contained in the one package
### These routines could be spread out over several packages
# Where to go after the ''action'' completes

===Getting actions recognised===
Before a Screen will even consider processing an action, it need to register those actions with the system. This is defined in <code>$self->{actions}</code> in the <code>new</code> method:

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

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

$self->{actions}
= [qw/new edit cancel view netunlink netlink repounlink repolink/];

$self->{appears} = .....

## any other code.....

return $self;
} ## end sub new

</pre>
Note that the terms listed in the <code>$self->{actions}</code> array are the same terms as keys in the action buttons.

===Making the buttons===
The Buttons are the form submit buttons, the things that make the work flow to the next stage.

The <code>$s->render_action_buttons</code> function takes a hash, which describes the set of buttons to display:
<pre>
my %buttons = (
cancel => $self->phrase( "action:cancel:title" ), # Is defined as "Cancel"
update => $self->phrase( "action:update:title" ), # Is defined as "Update"
_order => [ "update", "cancel" ],
_class => "ep_form_button_bar"
);
$f->appendChild( $s->render_action_buttons( %buttons ) );
</pre>
* <code>cancel => $self->phrase( "action:cancel:title" )</code> describe one action button: the internal name for the action and the text to be used for that button. You may have any number of buttons.
*<code>_order</code> is a reference to a list defining the order for the buttons. With nothing defined, the order will be random.
*<code>_class</code> defines the css class to give to the div that contains the buttons.

The above code would produce the following (x)html:
<pre>
<div class="ep_form_button_bar">
<input type="submit" class="ep_form_action_button"
onclick="return EPJS_button_pushed( '_action_update' )"
name="_action_update" value="Update">
<input type="submit" class="ep_form_action_button"
onclick="return EPJS_button_pushed( '_action_cancel' )"
name="_action_cancel" value="Cancel">
</div>
</pre>

===Where the actions are processed===
The actions are processed in a "Screen", a perl package.
The form being submitted therefor needs to contain a reference to that package:

$f->appendChild( $s->render_hidden_field( "screen", "Orgs"));

This would call the package <code>EPrints::Plugin::Screen::Orgs</code>, and try to process the selected action in there

(Yes, this means that one can have the same action in multiple Screens, as well as multiple action in the same Screen)

===Processing the actions===
The EPrints processor system calls a specified action in a named package (as detailed above)

For each possible action, two functions needed: <code>allow_''action''</code> and <code>action_''action''</code>... where ''action'' is the key given in the buttons hash above.

====The ''allow'' test====
The EPrints processor will always test to see if the user is permitted to perform an action.
A "True" return will permit the action.
<pre>
sub allow_cancel
{
return 1; # everyone can do this "cancel" action
}

sub allow_update
{
my( $self ) = @_;
return $self->can_edit; # Only users who have "can_edit" permissions can do this "update" action
}
</pre>

====The actual ''action'' routines====
Assuming that the user is permitted to do the action, then EPrints processor will call the appropriate action routine:
<pre>
sub action_cancel
{
my( $self ) = @_;

# Do stuff

}
</pre>

====Getting the parameters====
The parameters are collected from the session:

my $oname = $self->{session}->param( 'oarj_oname' );

One could be a bit more conservative:

<pre>
my %params;

# Have we got any parameters (should be a yes, actions are set in parameters)
if ($self->{session}->have_parameters)
{

# Get a list of all the parameters passed in
my @param_list = $self->{session}->param;

# build up a hash of all the parameters
foreach my $p (@param_list) {
$params{$p} = $self->{session}->param( $p );
}
};
</pre>

.... of course one would assume that, having written the action handler, you know what parameters to expect, and can just ask for them directly!

===Where to go after the action completes===
By default, the EPrints processor will then render whatever's in the render routine for the package that the action routines are in.
If you want the EPrints processor to use a different package to render something to the page, then:
<source lang="perl">
sub action_cancel
{
my( $self ) = @_;

# Do stuff
$self->{processor}->{screenid} = "My::Package";
}
</source>
will call the <code>render</code> routine in the package <code>EPrints::Plugin::Screen::My::Package</code> whilst:
<source lang="perl">
sub action_cancel
{
my( $self ) = @_;

# Do stuff
$self->{processor}->{redirect} = "http://wiki.eprints.org";
}
</source>
will redirect the page to the url specified (in this case to the wiki homepage)

Return to the main [[Screen_Plugins]] page.

API:EPrints/DataObj/Subject

2016-01-06T14:59:08Z

Alan.stiles@open.ac.uk: /* DESCRIPTION */ typo correction

{{API}}{{Pod2Wiki}}{{API:Source|file=perl_lib/EPrints/DataObj/Subject.pm|package_name=EPrints::DataObj::Subject}}[[Category:API|SUBJECT]][[Category:API:EPrints/DataObj|SUBJECT]][[Category:API:EPrints/DataObj/Subject|SUBJECT]]<div>


==NAME==
'''EPrints::DataObj::Subject''' - Class and methods relating to the subejcts tree.





==DESCRIPTION==
This class represents a single node in the subejcts tree. It also contains a number of methods for handling the entire tree.

EPrints::DataObj::Subject is a subclass of EPrints::DataObj

* $thing = EPrints::DataObj::Subject->get_system_field_info
: Return an array describing the system metadata of the Subject dataset.

* $subject = EPrints::DataObj::Subject->new( $session, $subjectid )
: Create a new subject object given the id of the subject. The values for the subject are loaded from the database.

* $subject = EPrints::DataObj::Subject->new_from_data( $session, $data )
: Construct a new subject object from a hash reference containing the relevant fields. Generally this method is only used to construct new Subjects coming out of the database.

* $success = $subject->commit( [$force] )
: Commit this subject to the database, but only if any fields have changed since we loaded it.

: If $force is set then always commit, even if there appear to be no changes.

* $success = $subject->remove
: Remove this subject from the database.

* $dataset = EPrints::DataObj::Subject->get_dataset_id
: Returns the id of the [[API:EPrints/DataSet|EPrints::DataSet]] object to which this record belongs.

* EPrints::DataObj::Subject::remove_all( $session )
: Static function.

: Remove all subjects from the database. Use with care!

* $subject = $subject->top()
: Returns the subject that is at the top of this subject's tree (which may be this subject).

: Returns undef if the subject is not part of a tree.

* $child_subject = $subject->create_child( $id, $name, $depositable )
: Similar to EPrints::DataObj::Subject::create, but this creates the new subject as a child of the current subject.

* @children = $subject->get_children
: Return a list of EPrints::DataObj::Subject objects which are direct children of the current subject.

* @parents = $subject->get_parents
: Return a list of EPrints::DataObj::Subject objects which are direct parents of the current subject.

* $boolean = $subject->can_post( [$user] )
: Determines whether the given user can post in this subject.

: Currently there is no way to configure subjects for certain users, so this just returns the true or false depending on the "depositable" flag.

* $xhtml = $subject->render_with_path( $session, $topsubjid )
: Return the name of this subject including it's path from $topsubjid.

: $topsubjid must be an ancestor of this subject.

: eg.

: Library of Congress > B Somthing > BC Somthing more Detailed

* @paths = $subject->get_paths( $session, $topsubjid )
: This function returns all the paths from this subject back up to the specified top subject.

: @paths is an array of array references. Each of the inner arrays is a list of subject id's describing a path down the tree from $topsubjid to $session.

* $subject_pairs = $subject->get_subjects ( [$postable_only], [$show_top_level], [$nes_tids], [$no_nest_label] )
: Return a reference to an array. Each item in the array is a two element list.

: The first element in the list is an identifier string.

: The second element is a utf-8 string describing the subject (in the current language), including all the items above it in the tree, but only as high as this subject.

: The subjects which are returned are this item and all its children, and childrens children etc. The order is it returns this subject, then the first child of this subject, then children of that (recursively), then the second child of this subject etc.

: If $postable_only is true then filter the results to only contain subjects which have the "depositable" flag set to true.

: If $show_top_level is not true then the pair representing the current subject is not included at the start of the list.

: If $nest_ids is true then each then the ids retured are nested so that the ids of the children of this subject are prefixed with this subjects id and a colon, and their children are prefixed by their nested id and a colon. eg. L:LC:LC003 rather than just "LC003"

: if $no_nest_label is true then the subject label only contains the name of the subject, not the higher level ones.

: A default result from this method would look something like this:

<pre> [
[ "D", "History" ],
[ "D1", "History: History (General)" ],
[ "D111", "History: History (General): Medieval History" ]
]</pre>

* ( $subject_map, $reverse_map ) = EPrints::DataObj::Subject::get_all( $session )
: Get all the subjects for the current archvive of $session.

: $subject_map is a reference to a hash. The keys of the hash are the id's of the subjects. The values of the hash are the EPrint::Subject object relating to that id.

: $reverse_map is a reference to a hash. Each key is the id of a subject. Each value is a reference to an array. The array contains a EPrints::DataObj::Subject objects, one for each child of the subject with the id. The array is sorted by the labels for the subjects, in the current language.

* $count = $subject->count_eprints( $dataset )
: Return the number of eprints in the dataset which are in this subject or one of its decendants. Search all fields of type subject.

* $boolean = EPrints::DataObj::Subject::valid_id( $id )
: Return true if the string is an acceptable identifier for a subject.

: This does not check all possible illegal values, yet.

* $subj->render()
: undocumented






==COPYRIGHT==
Copyright 2000-2011 University of Southampton.

This file is part of EPrints http://www.eprints.org/.

EPrints is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

EPrints is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with EPrints. If not, see http://www.gnu.org/licenses/.

Training Video:Browse View configuration

2015-11-27T11:32:05Z

Alan.stiles@open.ac.uk: Added text to intro and what you need to know / will learn. Added test Yourself and More Reading options

[[Category:Howto]]
[[Category:Training_Video|Browse View Configuration]]
[[Category:Documentation_Needed]]

==Introduction==

This video explains what the browse views are, how they are defined and how to define new views. It shows best practice ways to modify the default configuration and how to use the command line administration tools to optimise the performance of your server in creating and updating views.

==What You Will Learn==

* What a browse view is
* What are 'menu' and 'list' views
* How to create a new view
* How to change the way menu and lists views are rendered
* How to amend the default configuration without changing the existing config files
* How to regenerate the views via the admin interface, the command line and via scheduled tasks

==What You Should Already Know==

* Familiarity with the EPrints admin interface
* A basic understanding of PERL and how EPrints uses it
* Basic idea of how eprints uses configuration files

==Resources==

Each resource on this page (video, document, block of wiki text) should have a similar format to the Video section below.

=== Video===
The Video can be found at [http://youtu.be/Ap_u7_MCnhI http://youtu.be/Ap_u7_MCnhI].
====Index====
* [http://youtu.be/Ap_u7_MCnhI?t=0m00s 0:00 - What is a browse view]
* [http://youtu.be/Ap_u7_MCnhI?t=0m50s 0:50 - .include files (unbranded lists)]
* [http://youtu.be/Ap_u7_MCnhI?t=1m20s 1:20 - columns and pages on browse menus]
* [http://youtu.be/Ap_u7_MCnhI?t=1m50s 1:50 - configuration file overview (from front end)]
* [http://youtu.be/Ap_u7_MCnhI?t=2m50s 2:50 - multiple-menu views]
* [http://youtu.be/Ap_u7_MCnhI?t=3m30s 3:30 - value ranges on menus]
* [http://youtu.be/Ap_u7_MCnhI?t=4m24s 4:24 - variations on lists]
* [http://youtu.be/Ap_u7_MCnhI?t=4m47s 4:47 - hideempty]
* [http://youtu.be/Ap_u7_MCnhI?t=5m43s 5:43 - regenerating browse views]
* [http://youtu.be/Ap_u7_MCnhI?t=8m08s 8:08 - reloading the configuration]
* [http://youtu.be/Ap_u7_MCnhI?t=9m11s 9:11 - create new browse view (on the command line)]
* [http://youtu.be/Ap_u7_MCnhI?t=13m27s 13:27 - controlling columns on menus]
* [http://youtu.be/Ap_u7_MCnhI?t=13m48s 13:48 - reloading the configuration and refreshing the views (on the command line)]
* [http://youtu.be/Ap_u7_MCnhI?t=15m59s 15:59 - change rendering of browse list]
* [http://youtu.be/Ap_u7_MCnhI?t=16m20s 16:20 - creating render function]
* [http://youtu.be/Ap_u7_MCnhI?t=18m30s 18:30 - creating a DOM object]
* [http://youtu.be/Ap_u7_MCnhI?t=19m42s 19:42 - rendering an eprint with a custom citation style]
* [http://youtu.be/Ap_u7_MCnhI?t=20m30s 20:30 - generating just one view]
* [http://youtu.be/Ap_u7_MCnhI?t=21m35s 21:35 - running epadmin test]
* [http://youtu.be/Ap_u7_MCnhI?t=22m55s 22:55 - example of custom rendered browse view]
* [http://youtu.be/Ap_u7_MCnhI?t=24m13s 24:13 - set citation style on a view list]
* [http://youtu.be/Ap_u7_MCnhI?t=24m44s 24:44 - creating a citation style]
* [http://youtu.be/Ap_u7_MCnhI?t=26m50s 26:50 - optimising browse view generation]
* [http://youtu.be/Ap_u7_MCnhI?t=27m37s 27:37 - increasing the browse view timeout]
* [http://youtu.be/Ap_u7_MCnhI?t=28m08s 28:08 - max items parameter]
* [http://youtu.be/Ap_u7_MCnhI?t=28m40s 28:40 - finding documentation on the EPrints wiki]
* [http://youtu.be/Ap_u7_MCnhI?t=30m05s 30:05 - setting max_list_age and max_menu_age (witout modifying default configuration files)]
* [http://youtu.be/Ap_u7_MCnhI?t=32m10s 32:10 - modifying existing configuration with a loop]
* [http://youtu.be/Ap_u7_MCnhI?t=35m38s 35:38 - confirming properties are set]
* [http://youtu.be/Ap_u7_MCnhI?t=37m35s 37:35 - nightly generation of single browse views]

==== The Video====
<youtube>Ap_u7_MCnhI</youtube>

====Notes, Errata and Additional Information====

Any notes, version information, errata, etc concerned with this video

* EPrints 3.3.14

==Test Yourself==

* Create a new view to show items by publication in 2 columns
* Modify this view to show 3 columns
* Create a render function to add some simple text to the list items
* Modify the function to add the eprintid field to the list items

==More Reading==

* [[Adding_new_views | Adding New Views]]
* [[Views.pl | The default views configuration ]]

Training Video:Browse View configuration

2015-11-27T10:56:38Z

Alan.stiles@open.ac.uk: /* Introduction */

[[Category:Howto]]
[[Category:Training_Video|Browse View Configuration]]
[[Category:Documentation_Needed]]

==Introduction==

In this video you will learn what browse views are, how to create a new browse view, how to regenerate the views and how to change the way views are displayed.

==What You Will Learn==

* Learning Objective 1
* Learning Objective 2
* Learning Objective 3

==What You Should Already Know==

* Prerequisite 1 with links if appropriate
* Prerequisite 2 with links if appropriate
* Prerequisite 3 with links if appropriate

==Resources==

Each resource on this page (video, document, block of wiki text) should have a similar format to the Video section below.

=== Video===
The Video can be found at [http://youtu.be/Ap_u7_MCnhI http://youtu.be/Ap_u7_MCnhI].
====Index====
* [http://youtu.be/Ap_u7_MCnhI?t=0m00s 0:00 - What is a browse view]
* [http://youtu.be/Ap_u7_MCnhI?t=0m50s 0:50 - .include files (unbranded lists)]
* [http://youtu.be/Ap_u7_MCnhI?t=1m20s 1:20 - columns and pages on browse menus]
* [http://youtu.be/Ap_u7_MCnhI?t=1m50s 1:50 - configuration file overview (from front end)]
* [http://youtu.be/Ap_u7_MCnhI?t=2m50s 2:50 - multiple-menu views]
* [http://youtu.be/Ap_u7_MCnhI?t=3m30s 3:30 - value ranges on menus]
* [http://youtu.be/Ap_u7_MCnhI?t=4m24s 4:24 - variations on lists]
* [http://youtu.be/Ap_u7_MCnhI?t=4m47s 4:47 - hideempty]
* [http://youtu.be/Ap_u7_MCnhI?t=5m43s 5:43 - regenerating browse views]
* [http://youtu.be/Ap_u7_MCnhI?t=8m08s 8:08 - reloading the configuration]
* [http://youtu.be/Ap_u7_MCnhI?t=9m11s 9:11 - create new browse view (on the command line)]
* [http://youtu.be/Ap_u7_MCnhI?t=13m27s 13:27 - controlling columns on menus]
* [http://youtu.be/Ap_u7_MCnhI?t=13m48s 13:48 - reloading the configuration and refreshing the views (on the command line)]
* [http://youtu.be/Ap_u7_MCnhI?t=15m59s 15:59 - change rendering of browse list]
* [http://youtu.be/Ap_u7_MCnhI?t=16m20s 16:20 - creating render function]
* [http://youtu.be/Ap_u7_MCnhI?t=18m30s 18:30 - creating a DOM object]
* [http://youtu.be/Ap_u7_MCnhI?t=19m42s 19:42 - rendering an eprint with a custom citation style]
* [http://youtu.be/Ap_u7_MCnhI?t=20m30s 20:30 - generating just one view]
* [http://youtu.be/Ap_u7_MCnhI?t=21m35s 21:35 - running epadmin test]
* [http://youtu.be/Ap_u7_MCnhI?t=22m55s 22:55 - example of custom rendered browse view]
* [http://youtu.be/Ap_u7_MCnhI?t=24m13s 24:13 - set citation style on a view list]
* [http://youtu.be/Ap_u7_MCnhI?t=24m44s 24:44 - creating a citation style]
* [http://youtu.be/Ap_u7_MCnhI?t=26m50s 26:50 - optimising browse view generation]
* [http://youtu.be/Ap_u7_MCnhI?t=27m37s 27:37 - increasing the browse view timeout]
* [http://youtu.be/Ap_u7_MCnhI?t=28m08s 28:08 - max items parameter]
* [http://youtu.be/Ap_u7_MCnhI?t=28m40s 28:40 - finding documentation on the EPrints wiki]
* [http://youtu.be/Ap_u7_MCnhI?t=30m05s 30:05 - setting max_list_age and max_menu_age (witout modifying default configuration files)]
* [http://youtu.be/Ap_u7_MCnhI?t=32m10s 32:10 - modifying existing configuration with a loop]
* [http://youtu.be/Ap_u7_MCnhI?t=35m38s 35:38 - confirming properties are set]
* [http://youtu.be/Ap_u7_MCnhI?t=37m35s 37:35 - nightly generation of single browse views]

==== The Video====
<youtube>Ap_u7_MCnhI</youtube>

====Notes, Errata and Additional Information====

Any notes, version information, errata, etc concerned with this video

* EPrints 3.3.14

==Test Yourself==

Exercises as appropriate to allow the learner to practice the subject of the page.

==More Reading==

* Wiki page 1
* Wiki page 2
* Wiki page 3

Training Video:New Field Bazaar Package

2015-11-19T17:25:00Z

Alan.stiles@open.ac.uk: Applied the template

[[Category:Howto]]
[[Category:Training_Video|New Field Bazaar Package]]

==Introduction==

This videa is a walkthrough of converting a new field as created in [[Training_Video:Add_A_Field]] into a bazaar package, including modifying the workflow.

==What You Will Learn==

* How to build a bazaar package
* How to modify the workflow with a bazaar package
* Adding missing phrases to a bazaar package

==What You Should Already Know==

* How to access EPrints administration areas
* How to add a field to EPrints [[Training_Video:Add_A_Field]]
* Basics of Perl
* Basics of XML

==Resources==

=== Video===
The Video can be found at [http://youtu.be/gKxmXuFAH3A http://youtu.be/gKxmXuFAH3A].
====Index====
* [http://youtu.be/gKxmXuFAH3A?t=00m00s 00:00 - introduction]
* [http://youtu.be/gKxmXuFAH3A?t=00m15s 00:15 - identify new field to add to package]
* [http://youtu.be/gKxmXuFAH3A?t=00m25s 00:25 - create new bazaar package]
* [http://youtu.be/gKxmXuFAH3A?t=01m32s 01:32 - move phrase file to lib]
* [http://youtu.be/gKxmXuFAH3A?t=02m25s 02:25 - copy field definition to lib subdirectory]
* [http://youtu.be/gKxmXuFAH3A?t=03m07s 03:07 - creating a plugin to modify the workflow]
* [http://youtu.be/gKxmXuFAH3A?t=03m50s 03:50 - key functions for a plugin]
* [http://youtu.be/gKxmXuFAH3A?t=04m40s 04:40 - pull sample plugin code to use as base for new plugin]
* [http://youtu.be/gKxmXuFAH3A?t=05m20s 05:20 - modify the sample to reflect new plugin]
* [http://youtu.be/gKxmXuFAH3A?t=06m12s 06:12 - describe modifications to workflow]
* [http://youtu.be/gKxmXuFAH3A?t=07m00s 07:00 - add plugin code to bazaar package]
* [http://youtu.be/gKxmXuFAH3A?t=07m20s 07:20 - add the control screen details]
* [http://youtu.be/gKxmXuFAH3A?t=08m00s 08:00 - remove explicit entries from the workflow]
* [http://youtu.be/gKxmXuFAH3A?t=08m38s 08:38 - enable new plugin]
* [http://youtu.be/gKxmXuFAH3A?t=09m05s 09:05 - debugging]
* [http://youtu.be/gKxmXuFAH3A?t=10m55s 10:55 - test new field in workflow and add field phrase]
* [http://youtu.be/gKxmXuFAH3A?t=11m30s 11:30 - move phrase from webcfg.xml to plugin phrase file]
* [http://youtu.be/gKxmXuFAH3A?t=12m10s 12:10 - update the bazaar package to account for changes]
* [http://youtu.be/gKxmXuFAH3A?t=12m25s 12:25 - publish new package to eprints bazaar and test installation]
* [http://youtu.be/gKxmXuFAH3A?t=14m30s 14:30 - install package from bazaar]
* [http://youtu.be/gKxmXuFAH3A?t=15m00s 15:00 - more debugging ]
* [http://youtu.be/gKxmXuFAH3A?t=15m23s 15:23 - add missing files to the package - phrases and cfg files]
* [http://youtu.be/gKxmXuFAH3A?t=16m08s 16:08 - publish new version to bazaar]
* [http://youtu.be/gKxmXuFAH3A?t=17m00s 17:00 - test installation on fresh repository]

==== The Video====
<youtube>gKxmXuFAH3A</youtube>

====Notes, Errata and Additional Information====

* EPrints 3.3.14
* Ubuntu 15.04

==Test Yourself==

* Create a bazaar package to add a new field to the repository
* Modify the bazaar package to include the new field in the workflow

==More Reading==

* [[Training_Video:Add_A_Field | How to add a field]]
* [[Training_Video:Export_Plugin_Bazaar_Package | Building an exporter bazaar package]]

Training Video:Default Fields

2015-11-19T16:21:37Z

Alan.stiles@open.ac.uk: Apply template

[[Category:Howto]]
[[Category:Training_Video|Default Fields]]

[[Category:Howto]]
[[Category:Training_Video|Template]]

==Introduction==

This video covers what default values are and how to configure EPrints to apply default values to fields on items in the repository

==What You Will Learn==

* What a default value is
* How to add a default value to an existing field
* How to access details of the currently logged-in user
* How to find system field names for fields in the workflow

==What You Should Already Know==

* How to access the EPrints administration functions

==Resources==

=== Video===
The Video can be found at [http://youtu.be/79vlrBHWpOU http://youtu.be/79vlrBHWpOU].
====Index====
* [http://youtu.be/79vlrBHWpOU?t=00m00s 00:00 - introduction]
* [http://youtu.be/79vlrBHWpOU?t=00m05s 00:05 - selecting a field for our first, simple example]
* [http://youtu.be/79vlrBHWpOU?t=00m50s 00:50 - finding the example field's name through the admin menu]
* [http://youtu.be/79vlrBHWpOU?t=01m40s 01:40 - finding the appropriate configuration file through the admin menu]
* [http://youtu.be/79vlrBHWpOU?t=03m10s 03:10 - editing the correct configuration file (eprint_fields_default.pl)]
* [http://youtu.be/79vlrBHWpOU?t=04m05s 04:05 - saving and reloading configuration]
* [http://youtu.be/79vlrBHWpOU?t=04m15s 04:15 - adding a new item in My Deposits]
* [http://youtu.be/79vlrBHWpOU?t=04m25s 04:25 - verifying it worked]
* [http://youtu.be/79vlrBHWpOU?t=05m10s 05:10 - a more complex example]
* [http://youtu.be/79vlrBHWpOU?t=06m30s 06:30 - editing a configuration file via the command line to add a default value based on current user information]
* [http://youtu.be/79vlrBHWpOU?t=07m45s 07:45 - finding the name of the field to be used as a conditional on the second example]
* [http://youtu.be/79vlrBHWpOU?t=08m00s 08:00 - alter the new default value based on the logged-in user]
* [http://youtu.be/79vlrBHWpOU?t=08m35s 08:35 - verifying the code's syntax is correct]
* [http://youtu.be/79vlrBHWpOU?t=08m45s 08:45 - restarting apache]
* [http://youtu.be/79vlrBHWpOU?t=08m50s 08:50 - adding a new item to test the changes]
* [http://youtu.be/79vlrBHWpOU?t=09m00s 09:00 - verify the first condition worked]
* [http://youtu.be/79vlrBHWpOU?t=09m05s 09:05 - removing organisation from the user's profile]
* [http://youtu.be/79vlrBHWpOU?t=09m25s 09:25 - verifying the second condition worked]

==== The Video====
<youtube>79vlrBHWpOU</youtube>

====Notes, Errata and Additional Information====

* EPrints 3.3.14
* Ubuntu 15.04

==Test Yourself==

* modify the configuration to add a default value to a field
* add a default value based on current user information

==More Reading==

Training Video:Automatic Fields

2015-11-19T16:08:20Z

Alan.stiles@open.ac.uk: applied last part of template

[[Category:Howto]]
[[Category:Training_Video|Automatic Fields]]

==Introduction==

This video covers details of how field values can be automatically assigned when an item is saved to the repository. It covers how to configure automatic fields and the best ways of extending the default configuration files. It also shows how to build a simple browse view over an automated field.

==What You Will Learn==

* How automatic fields are configured
* How to automate an existing field
* How to add a new field and calculate its value automatically
* How to apply automated fields to existing items
* How to add a simple browse view over an automated field
* Debugging issues when applying configuration changes

==What You Should Already Know==

* How to access the EPrints administration functions
* Basics of PERL and XML syntaxes [[Perl_101_for_EPrints | Basic guide to PERL in EPrints]]

==Resources==

===Video===
The video is accessible from here : [http://youtu.be/YC_W23YfJ1A http://youtu.be/YC_W23YfJ1A]

====Index====
* [http://youtu.be/YC_W23YfJ1A?t=00m00s 00:00 - introduction]
* [http://youtu.be/YC_W23YfJ1A?t=00m30s 00:30 - examine default config for automatic fields]
* [http://youtu.be/YC_W23YfJ1A?t=01m30s 01:30 - demonstrate automatic fields on a thesis]
* [http://youtu.be/YC_W23YfJ1A?t=02m00s 02:00 - demonstrate automatic fields on a patent]
* [http://youtu.be/YC_W23YfJ1A?t=03m10s 03:10 - create new cfg file to add new automatic field function]
* [http://youtu.be/YC_W23YfJ1A?t=04m15s 04:15 - copy original automatic fields function to new variable]
* [http://youtu.be/YC_W23YfJ1A?t=05m45s 05:45 - configure new function with a call to the original function]
* [http://youtu.be/YC_W23YfJ1A?t=06m15s 06:15 - create a new field to hold individual title words]
* [http://youtu.be/YC_W23YfJ1A?t=07m30s 07:30 - define new field as volatile and explain why]
* [http://youtu.be/YC_W23YfJ1A?t=08m00s 08:00 - add function to populate new field automatically]
* [http://youtu.be/YC_W23YfJ1A?t=09m00s 09:00 - test new configuration]
* [http://youtu.be/YC_W23YfJ1A?t=09m20s 09:20 - debug a missing ';']
* [http://youtu.be/YC_W23YfJ1A?t=09m30s 09:30 - retest configuration and update database structure]
* [http://youtu.be/YC_W23YfJ1A?t=09m50s 09:50 - restart apache]
* [http://youtu.be/YC_W23YfJ1A?t=10m00s 10:00 - test new function]
* [http://youtu.be/YC_W23YfJ1A?t=10m40s 10:40 - add phrase for new field]
* [http://youtu.be/YC_W23YfJ1A?t=11m50s 11:50 - recommit all items in database to apply new automatic field]
* [http://youtu.be/YC_W23YfJ1A?t=12m20s 12:20 - add a browse view over new automatic field]
* [http://youtu.be/YC_W23YfJ1A?t=13m00s 13:00 - pushing new view to browse views configuration]
* [http://youtu.be/YC_W23YfJ1A?t=14m20s 14:20 - copy view phrases to new phrase file and edit for new view]
* [http://youtu.be/YC_W23YfJ1A?t=17m05s 17:05 - regenerate views]
* [http://youtu.be/YC_W23YfJ1A?t=18m00s 18:00 - correct an issue with new view names and regenerate views (verbose)]
* [http://youtu.be/YC_W23YfJ1A?t=19m40s 19:40 - look at new view and explain possible further modifications]

====The Video====
<youtube>YC_W23YfJ1A</youtube>

====Notes, Errata and Additional Information====

* EPrints version 3.3.14
* Ubuntu 15.04

==Test Yourself==

* Add automation to an existing field
* Add a new automatic field
* apply the new automatic value to all existing records
* Create a browse view based on the new field

==More Reading==

* [[Adding_new_views | Adding New Views]]

Training Video:Automatic Fields

2015-11-19T16:02:01Z

Alan.stiles@open.ac.uk: /* Video */ applying new template

[[Category:Howto]]
[[Category:Training_Video|Automatic Fields]]

==Introduction==

Walkthrough of adding an automatic metadata field to a repository, including basing a browse view on it.

==Introduction==

This video covers details of how field values can be automatically assigned when an item is saved to the repository. It covers how to configure automatic fields the best ways of extending the default configuration files.

==What You Will Learn==

* How automatic fields are configured
* How to automate an existing field
* How to add a new field and calculate its value automatically
* How to apply automated fields to existing items
* How to add a simple browse view over an automated field
* Debugging issues when applying configuration changes

==What You Should Already Know==

* How to access the EPrints administration functions
* Basics of PERL and XML syntaxes [[Perl_101_for_EPrints | Basic guide to PERL in EPrints]]

==Resources==

===Video===
The video is accessible from here : [http://youtu.be/YC_W23YfJ1A http://youtu.be/YC_W23YfJ1A]

====Index====
* [http://youtu.be/YC_W23YfJ1A?t=00m00s 00:00 - introduction]
* [http://youtu.be/YC_W23YfJ1A?t=00m30s 00:30 - examine default config for automatic fields]
* [http://youtu.be/YC_W23YfJ1A?t=01m30s 01:30 - demonstrate automatic fields on a thesis]
* [http://youtu.be/YC_W23YfJ1A?t=02m00s 02:00 - demonstrate automatic fields on a patent]
* [http://youtu.be/YC_W23YfJ1A?t=03m10s 03:10 - create new cfg file to add new automatic field function]
* [http://youtu.be/YC_W23YfJ1A?t=04m15s 04:15 - copy original automatic fields function to new variable]
* [http://youtu.be/YC_W23YfJ1A?t=05m45s 05:45 - configure new function with a call to the original function]
* [http://youtu.be/YC_W23YfJ1A?t=06m15s 06:15 - create a new field to hold individual title words]
* [http://youtu.be/YC_W23YfJ1A?t=07m30s 07:30 - define new field as volatile and explain why]
* [http://youtu.be/YC_W23YfJ1A?t=08m00s 08:00 - add function to populate new field automatically]
* [http://youtu.be/YC_W23YfJ1A?t=09m00s 09:00 - test new configuration]
* [http://youtu.be/YC_W23YfJ1A?t=09m20s 09:20 - debug a missing ';']
* [http://youtu.be/YC_W23YfJ1A?t=09m30s 09:30 - retest configuration and update database structure]
* [http://youtu.be/YC_W23YfJ1A?t=09m50s 09:50 - restart apache]
* [http://youtu.be/YC_W23YfJ1A?t=10m00s 10:00 - test new function]
* [http://youtu.be/YC_W23YfJ1A?t=10m40s 10:40 - add phrase for new field]
* [http://youtu.be/YC_W23YfJ1A?t=11m50s 11:50 - recommit all items in database to apply new automatic field]
* [http://youtu.be/YC_W23YfJ1A?t=12m20s 12:20 - add a browse view over new automatic field]
* [http://youtu.be/YC_W23YfJ1A?t=13m00s 13:00 - pushing new view to browse views configuration]
* [http://youtu.be/YC_W23YfJ1A?t=14m20s 14:20 - copy view phrases to new phrase file and edit for new view]
* [http://youtu.be/YC_W23YfJ1A?t=17m05s 17:05 - regenerate views]
* [http://youtu.be/YC_W23YfJ1A?t=18m00s 18:00 - correct an issue with new view names and regenerate views (verbose)]
* [http://youtu.be/YC_W23YfJ1A?t=19m40s 19:40 - look at new view and explain possible further modifications]

====The Video====
<youtube>YC_W23YfJ1A</youtube>

==Notes==

Training Video:Export Plugin Bazaar Package

2015-11-19T12:31:05Z

Alan.stiles@open.ac.uk: /* Video */ Added Resources level 2 header

[[Category:EPrints_3_Plugins]]
[[Category:Howto]]
[[Category:Training_Video|Export Plugin Bazaar Package]]
[[Category:EPrints_Bazaar]]

==Introduction==

This video explains how to create a simple export plugin and wrap it as a bazaar package. Export plugins allow you to present the data in EPrints in any format. Bazaar Packages enable you to share this format with others so your work can be re-used.

==What you will learn==

* What an export plugin does, and how to write a simple, text-based example
* How to ensure your plugin is compatible with different installations of EPrints (single and multiple repository)
* Testing the plugin
* Creating associated files and compiling the plugin
* Sharing the plugin with the EPrints community and keeping it up to date

==What you should already know==

* How to log in to EPrints as an administrator
* How to use command line tools:
** changing directories
** listing contents of folders
** copying, moving and editing text files
** restarting the web server
** creating new directories
* Familiarity with Perl (the example modifies an existing plugin, so you need to be able to read and modify code following existing structures)

==Resources==
===Video===

The video can be found below or on YouTube at: http://youtu.be/JdZ8YCWLOJk

====Index====

* [http://www.youtube.com/watch?v=JdZ8YCWLOJk 0:00 - create a new ASCII Citation based “hello” export plugin]
* [http://www.youtube.com/watch?v=JdZ8YCWLOJk&t=200 3:20 - move plugin to /lib/plugins /folder]
* [http://www.youtube.com/watch?v=JdZ8YCWLOJk&t=310 5:10 - disable “hello” plugin in /lib/ as a globally enabled plugin]
* [http://www.youtube.com/watch?v=JdZ8YCWLOJk&t=360 6:00 - enable “hello” plugin in /lib/ as a locally enabled plugin]
* [http://www.youtube.com/watch?v=JdZ8YCWLOJk&t=480 8:00 - create Bazaar package]
* [http://www.youtube.com/watch?v=JdZ8YCWLOJk&t=750 12:30 - install new Bazaar package on another repository and test it]
* [http://www.youtube.com/watch?v=JdZ8YCWLOJk&t=855 14:15 - create icon with Bazaar icon builder]
* [http://www.youtube.com/watch?v=JdZ8YCWLOJk&t=945 15:45 - move created icon to /lib/static/images/?]
* [http://www.youtube.com/watch?v=JdZ8YCWLOJk&t=1025 17:05 - install Wordle Generator Bazaar package to confirm image path]
* [http://www.youtube.com/watch?v=JdZ8YCWLOJk&t=1080 18:00 - move the icon image to /lib/static/images/epm/]
* [http://www.youtube.com/watch?v=JdZ8YCWLOJk&t=1140 19:00 - publish completed Bazaar package to Bazaar.org]
* [http://www.youtube.com/watch?v=JdZ8YCWLOJk&t=1180 19:40 - create new version of the ‘hello’ Bazaar package]

====The Video====

<youtube>JdZ8YCWLOJk</youtube>

====Notes, Errata and Additional Information====

* EPrints 3.3.14
* Ubuntu
* Vim text editor

==Test Yourself==

Plugin Exercises (includes other kinds of plugins):

[http://www.eprints.org/software/training/programming/plugin_exercises.pdf Instructions]

[http://www.eprints.org/software/training/programming/plugin-scripts/ Starter files and examples]

==More Reading==

[http://www.eprints.org/software/training/programming/api_techniques.pdf More about the API to make your export plugin more useful]

[[Create Export Plugins|Many more examples of export plugins]]

[[How to write plugins]]

[[Instructions for local plugins]]

[[Tips to write plugins]]

[[:Category:Plugins|Category page with many examples of export plugins]]

Training Video:Add A Field

2015-11-19T12:30:00Z

Alan.stiles@open.ac.uk: /* Resources */ changed https to http

[[Category:Howto]]
[[Category:Training_Video|Template]]

==Introduction==

Walkthrough of adding a metadata field to a repository.

==What You Will Learn==

* How to add a field to the repository without editing core configuration files
* How to add new phrases and to include the new field in the Workflow
* How to add the field to the Abstract page

==What You Should Already Know==

* Be familiar with the structure of EPrints and the relationships between configuration, phrase and workflow files
* How to login as administrator and to edit text files on the server
* How to restart Apache

==Resources==

=== Video===
The Video can be found at [http://www.youtube.com/watch?v=1B5_dHStUTQ http://www.youtube.com/watch?v=1B5_dHStUTQ].
====Index====
* [http://www.youtube.com/watch?v=1B5_dHStUTQ&t=0m00s 00:00 Introduction]
* [http://www.youtube.com/watch?v=1B5_dHStUTQ&t=0m18s 00:18 Command line intro and basic set-up]
* [http://www.youtube.com/watch?v=1B5_dHStUTQ&t=0m45s 00:45 Look over the file: eprint_fields.pl]
* [http://www.youtube.com/watch?v=1B5_dHStUTQ&t=1m39s 01.39 Add new field to new file: z_local_eprints_fields.pl]
* [http://www.youtube.com/watch?v=1B5_dHStUTQ&t=2m33s 02.33 Use the add_dataset_field function to add the field]
* [http://www.youtube.com/watch?v=1B5_dHStUTQ&t=3m39s 03.39 Creating field of type ‘set’]
* [http://www.youtube.com/watch?v=1B5_dHStUTQ&t=4m28s 04.28 Commit the new field by using ‘epadmin update repoid’]
* [http://www.youtube.com/watch?v=1B5_dHStUTQ&t=5m28s 05.28 Add the new field to the eprint Workflow]
* [http://www.youtube.com/watch?v=1B5_dHStUTQ&t=6m34s 06.34 Add the phrases, set names and help text for the new field using the web UI]
* [http://www.youtube.com/watch?v=1B5_dHStUTQ&t=8m35s 08.35 Add the new field to the eprint Abstract page]
* [http://www.youtube.com/watch?v=1B5_dHStUTQ&t=9m15s 09.15 Overview of ‘eprint_render.pl’ file]
* [http://www.youtube.com/watch?v=1B5_dHStUTQ&t=10m45s 10.45 Run regenerate_abstracts to request and update to the Abstract page]
* [http://www.youtube.com/watch?v=1B5_dHStUTQ&t=11m35s 11.35 Move the phrases created using the web UI from zz_phrases.xml to z_local_fields.xml]

==== The Video====
<youtube>1B5_dHStUTQ</youtube>

====Notes, Errata and Additional Information====

* EPrints 3.3.14
* Ubuntu 15.04

==More Reading==

*[http://wiki.eprints.org/w/Metadata http://wiki.eprints.org/w/Metadata]

Training Video:Search Configuration

2015-11-19T12:26:37Z

Alan.stiles@open.ac.uk: applied new template

[[Category:Howto]]
[[Category:Training_Video|Search Configuration]]

==Introduction==

Configuring (and a little troubleshooting of) EPrints searches

==What You Will Learn==

* How to trace the cause of errors with searching
* What the indexer service is and how to restart it
* How to add fields to the advanced search
* How to create a new search function

==What You Should Already Know==

* How to access EPrints administration pages
* How to update EPrints configuration files

==Resources==

=== Video===
The Video can be found at [http://youtu.be/9soulfKp20A http://youtu.be/9soulfKp20A].

====Index====
* [http://youtu.be/9soulfKp20A?t=00m00s 00:00 - Introduction]
* [http://youtu.be/9soulfKp20A?t=00m32s 00:32 - Diagnosing Search Error]
* [http://youtu.be/9soulfKp20A?t=00m58s 00:58 - Checking the status of the Indexer]
* [http://youtu.be/9soulfKp20A?t=01m23s 01:23 - Description of Background Task Queue]
* [http://youtu.be/9soulfKp20A?t=01m47s 01:47 - Inspecting the error log]
* [http://youtu.be/9soulfKp20A?t=02m40s 02:40 - Starting the Indexer]
* [http://youtu.be/9soulfKp20A?t=02m50s 02:50 - Verifying the Indexer is working]
* [http://youtu.be/9soulfKp20A?t=03m10s 03:10 - Unsuccessful search (items not yet indexed)]
* [http://youtu.be/9soulfKp20A?t=03m35s 03:35 - Description of Search Configuration]
* [http://youtu.be/9soulfKp20A?t=04m22s 04:22 - Viewing Search Configuration files]
* [http://youtu.be/9soulfKp20A?t=06m27s 06:27 - Adding a new field to the advanced search]
* [http://youtu.be/9soulfKp20A?t=06m42s 06:42 - Viewing all fields on an EPrint]
* [http://youtu.be/9soulfKp20A?t=07m33s 07:33 - Verifying the change worked (reloading configuration)]
* [http://youtu.be/9soulfKp20A?t=08m20s 08:20 - All items indexed, verification of search function.]
* [http://youtu.be/9soulfKp20A?t=08m43s 08:43 - Creating a new search]
* [http://youtu.be/9soulfKp20A?t=10m28s 10:28 - Verifying new search]
* [http://youtu.be/9soulfKp20A?t=10m40s 10:40 - Adding new phrases]

==== The Video====
<youtube>9soulfKp20A</youtube>

====Notes, Errata and Additional Information====

* EPrints 3.3.14
* Ubuntu 15.04

==Test Yourself==

* run a search on an eprints repository
* Stop and Start the indexer via the web interface
* Add a new field to the advanced search
* Create a new search class

==More Reading==

* [[Training_Video:Search_Troubleshooting| Search Troubleshooting training video]]

Training Video:Subject Trees

2015-11-19T12:14:09Z

Alan.stiles@open.ac.uk: /* Video */ Added Resources level 2 heading

[[Category:Howto]]
[[Category:Training_Video|Subject Trees]]

==Introduction==

This video shows you how to manipulate subject trees in EPrints. Subject trees allow you to browse by hierarchies, such as subjects and departments.

==What You Will Learn==

* How to change display names of subject trees
* How to add a new node to a tree
* How to make bulk changes to subject files
* How to import a subject file
* How to export a subject tree

==What You Should Already Know==

* How to use the EPrints Admin interface
* Basic use of command line interface to run EPrints commands

== Resources ==
=== Video===
The Video can be found at http://www.youtube.com/watch?v=1rYT9krerxM.
====Index====
* [http://youtu.be/1rYT9krerxM 0:00 Introduction]
* [http://youtu.be/1rYT9krerxM?t=0m22s 0:22 Browsing by subject and divisions]
* [http://youtu.be/1rYT9krerxM?t=0m50s 0:50 Subject trees in the deposit workflow]
* [http://youtu.be/1rYT9krerxM?t=1m43s 1:43 Change name of subject tree]
* [http://youtu.be/1rYT9krerxM?t=2m45s 2:45 Properties of a subject]
* [http://youtu.be/1rYT9krerxM?t=3m55s 3:55 Verifying change in the workflow]
* [http://youtu.be/1rYT9krerxM?t=4m05s 4:05 Adding a new department to the divisions tree]
* [http://youtu.be/1rYT9krerxM?t=5m51s 5:51 Verifying change in the workflow]
* [http://youtu.be/1rYT9krerxM?t=6m40s 6:40 Description of subject tree import format]
* [http://youtu.be/1rYT9krerxM?t=8m14s 8:14 Creation of new tree in the subjects file]
* [http://youtu.be/1rYT9krerxM?t=14m02s 14:02 Importing subjects file]
* [http://youtu.be/1rYT9krerxM?t=14m40s 14:40 Verifying change in the workflow]
* [http://youtu.be/1rYT9krerxM?t=15m09s 15:09 Exporting the subject tree]
* [http://youtu.be/1rYT9krerxM?t=16m14s 16:14 Listing export options]
* [http://youtu.be/1rYT9krerxM?t=16m50s 16:50 XML export]
* [http://youtu.be/1rYT9krerxM?t=17m15s 17:15 Fixing bug in exporter]
* [http://youtu.be/1rYT9krerxM?t=17m55s 17:55 Exporting in subject format, writing to a file]
* [http://youtu.be/1rYT9krerxM?t=18m06s 18:06 Reordering subjects file to be more editable]

==== The Video====

<youtube>1rYT9krerxM</youtube>

====Notes, Errata and Additional Information====

Any notes, version information, errata, etc concerned with this video

* EPrints 3.3.14
* Ubuntu 15.04

==Test Yourself==

Use the admin interface to edit a subject

Create a subject tree in the basic text format, e.g.:

subjects:Name of Subject Tree:ROOT:0
subjA:First Subject Name:subjects:0
childA1:First Child Subject A:subjA:1
subjB:Second Subject Name:subjects:0
childB1:First Child Subject B:subjB:1
childB2:Second Child Subject B:subjB:1
subjC:Third Subject Name:subjects:0
childC1:First Child Subject C:subjC:1

Import this into the archive using the command line tool bin/import_subjects

Now add a new tree to show the organisation structure. Remember the system names must be unique across all subject trees, e.g.:

divisions:Name of Department Tree:ROOT:0
facA:Faculty A:divisions:0
deptA1:Department A1:facA:1
facB:Faculty B:divisions:0
deptB1:Department B1:facB:1
facC:Faculty C:divisions:0
deptC1:Department C1:facC:1
deptC2:Department C2:facC:1

Import this into the archive using the command line tool

Change the name of one of your new subjects using the admin interface

Now export that tree using the commandline tool bin/export [archivename] subject Subject

==More Reading==

* [[bin/import_subjects|Importing Subjects on the command line]]