Editing EPrints 3 Organisation Hierarchy

[[Category:Manual]]
[[Category:Subject Trees]]

EPrints 3 is supplied with a 'place-holder' organisation hierarchy which should be modified to represent your organisation.

== The Subjects File ==

An organisation hierarchy is stored in the same file as the subject tree.  In fact, any number of hierarchies or trees can be stored in this file.
 /opt/eprints3/archives/''archive_id''/cfg/subjects

== The Subjects File explained ==

Imagine your organisation looks like this:

* Acme Research Corporation
** Rocket Group
*** Solid Fuel Rockets Department
*** Liquid Fuel Rockets Department
** Spring Group
*** Large Spring Department
*** Huge Spring Department

You need to create a machine-readable representation of this.

Each hierarchy starts with a root:
 acme_division:Acme Research Corporation:ROOT:0
This tells EPrints that the top (or root) of the hierarchy (or tree) has a system name of acme_division, a human readable name of "Acme Research Corporation", is the root, and is not selectable.

Now we can add the groups:
 rockets:Rocket Group:acme_division:0
 springs:Spring Group:acme_division:0
This defines our two groups, and also defines the parent of them.  We've also chosen not to make these selectable, but you could if you wanted to.

Finally, we add the departments
 solid_fuel_rockets:Solid Fuel Rockets Department:rockets:1
 liquid_fuel_rockets:Liquid Fuel Rockets Department:rockets:1
 large_springs:Large Spring Department:springs:1
 huge_springs:Huge Sprint Department:springs:1

Generically, each line in the file is defined like this:
 <system name>:<human readable name>:<parent's system name>:<selectable (0 or 1)>
<strong>Important</strong>: it's essential that every system name in the subjects file is unique across the whole file, otherwise nodes will appear in the wrong trees.

== Modifying the subjects file ==

The simplest way to add your organisational structure is to replace the existing 'place-holder'.

Open the subjects file:
 pico /opt/eprints3/<archive id>/cfg/subjects

Find the line:
 divisions:University Structure:ROOT:0

This is the root of the current hierarchy.  Remove the whole tree by removing from the above line to the last line in the tree:
 sch_med:School of Medicine:fac_med:1

Insert your own hierarchy as described above, but be sure that the ROOT element has the system name <strong>divisions</strong>.

Attention: In case you included any other scheme in the subjects file, be aware to use document wide unique identifiers. They are not case sensitive! This means 'RZ' is the same as 'rz'.

== Importing the New Hierarchy ==

Run the import_subjects script:
 /opt/eprints3/bin/import_subjects <archive id>

You should now see your own hierarchy in the 'Divisions' box when submitting an eprint.

== Multilinguality ==

=== Writing the scheme in 'subjects' ===

If the scheme should reflect different languages it must be stored in XML-format. Anyway it is easiest when You start as above with the scheme in English, because by default the language settings in the automatical XML file will be 'en' (see below).

=== Generating 'subjects.xml' ===

To generate the initial 'subjects.xml' from the file 'subjects' execute

 /opt/eprints3/bin/import_subjects <archive id>
 /opt/eprints3/bin/export <archive id> subject XML > /opt/eprints3/archives/<archive id>/cfg/subjects.xml

=== Modifying 'subjects.xml' ===

The root of your organisation scheme will look like this in subjects.xml:

  <subject xmlns="http://eprints.org/ep2/data/2.0">
    <subjectid>divisions</subjectid>
    <rev_number>3</rev_number>
    <name>
      <item>
        <name>University of Osnabrück</name>
        <lang>en</lang>
      </item>
    </name>
    <parents>
      <item>ROOT</item>
    </parents>
    <depositable>FALSE</depositable>
  </subject>

Now you have to add a further <item>-block with the translation and to replace special characters by Unicode entities:

  <subject xmlns="http://eprints.org/ep2/data/2.0">
    <subjectid>divisions</subjectid>
    <rev_number>3</rev_number>
    <name>
      <item>
        <name>University of Osnabr&amp;#252;ck</name>
        <lang>en</lang>
      </item>
      <item>
        <name>Universit&amp;#228;t Osnabr&amp;#252;ck</name>
        <lang>de</lang>
      </item>
    </name>
    <parents>
      <item>ROOT</item>
    </parents>
    <depositable>FALSE</depositable>
  </subject>

Special characters, e.g. German umlauts, French accents and special symbols must be coded as XML-unicode characters (like &amp;#165; or &amp;#xA5; for the Yen-symbol &yen;). The &amp;yen; entity is not allowed.

This way you can add more languages as you like. Proceed with all other <subject>-blocks.

=== Apply the changes ===

At the last step the new 'subjects.xml' must imported into the system:

 /opt/eprints3/bin/import_subjects <archive id> -xml /opt/eprints3/archives/<archive id>/cfg/subjects.xml
 /opt/eprints3/bin/generate_views <archive id>

In some cases this is not enough to take effect. Then load the configurations into the web server and restart it. This can look like:

 /opt/eprints3/bin/epadmin reload <archive id>
 sudo /etc/init.d/apache2 restart