Difference between revisions of "Adding a Field to a Live Repository"

From EPrints Documentation
Jump to: navigation, search
m (Line return adjustments.)
 
(7 intermediate revisions by 4 users not shown)
Line 1: Line 1:
 
[[Category:Manual]]
 
[[Category:Manual]]
−
[[Category:Howto]]
+
[[Category:Metadata Fields]]
 +
[[Category: Out of Date]]
  
−
To add a field to a live eprints archive you have to modify the SQL tables.
+
=== EPrints 3.3+ ===
  
−
Before you start this you may wish to BackupTheDatabase.
+
Follow the instructions as you would for [[HOW TO: Add a New Field]].
  
−
This assumes you are adding a field to the "eprint" fields, not the "user" fields. If you are changing "user" then anywhere we have 4 actions, one for each of buffer, deletion, archive and inbox, you instead need a single action for "users".
+
As described there, you define your new fields in...
 +
* <code>/opt/eprints3/archives/ARCHIVEID/cfg/cfg.d/eprint_fields.pl</code> for EPrint-level metadata,
 +
* <code>/opt/eprints3/archives/ARCHIVEID/cfg/cfg.d/document_fields.pl</code> for document-level metadata (this file doesn't exist by default, but is honoured),  
 +
* and <code>/opt/eprints3/archives/ARCHIVEID/cfg/cfg.d/user_fields.pl</code> for user metadata, etc etc.
  
−
Adding fields of type "name" is beyond the scope of these instructions.
 
  
−
== Recipe (for Eprints 2.x)==
+
Since a repository's <code>eprint_fields.pl</code> will override a flavour's <code>eprint_fields.pl</code> based on them both having the same file name, should you only wish to add to a flavour's fields rather than replace them, you may prefer to give your archive's local version a file name such as <code>eprint_fields_local.pl</code>, and then inside have only your new field(s):
  
−
=== Step 1 - Shut down apache ===  
+
push @{$c->{fields}->{eprint}},
−
Shut down the web server. You don't want people using it while you make this change.
+
 +
{
 +
name => 'my_first_new_field',
 +
type => 'set',
 +
options => [
 +
    'yes',
 +
    'no',
 +
    'partial',
 +
],
 +
input_rows => 1,
 +
},
 +
 +
{
 +
name => 'my_second_new_field',
 +
type => 'set',
 +
options => [
 +
    'yes',
 +
    'no',
 +
    'partial',
 +
],
 +
input_rows => 1,
 +
},
 +
 +
;
  
−
=== Step 2 - Add configuration ===
 
−
Add the configuration for this field to MetadataFieldsConfig.pm - take note of which field you add this new field after. (from now on I'll refer to the previous field as ''prevfield''.
 
  
−
=== Step 3 - Add fields to database ===
+
Simply make sure your <code>push</code>, is adding your field to the correct dataset you wish to add fields to - in this case an <code>eprint</code> dataset.
  
−
Find out the SQL type of the field you are adding.
 
  
−
boolean
 
−
:: '''SET('TRUE','FALSE')'''
 
−
date
 
−
:: '''DATE'''
 
−
year, int
 
−
:: '''INTEGER'''
 
−
longtext
 
−
:: '''TEXT'''
 
−
subject,set,url,email,pagerange,text
 
−
:: '''VARCHAR(255)'''
 
  
−
Note that if the field is type multiple then this step is different.
+
Then, once you have added your new field definitions to the appropriate configuration file you can run ''update'' via [[API:bin/epadmin|epadmin]] from the shell.
  
−
For both steps the following replacements must be applied to the MySQL code given:
 
  
−
* Replace ''type'' with the SQL type appropriate to the field you are adding.
+
You can begin with a dry run to see what would happen:
−
* Replace ''newfieldname'' with the name of the field you're adding
 
−
* Replace ''prevfield'' with the name of the (non-multiple) field proceeding the field you are adding. If prevfield is a multiple then use the first non-multiple field proceeding your new field. (not used for multiple fields)
 
  
−
''Now only do step 3a or 3b depending if this field is multiple or not''
+
./bin/epadmin update_dry_run ARCHIVEID
  
−
==== Step 3a - Adding a normal field ====
+
Then once confident proceed for real:
  
−
In the database (log into CommandLineMySQL) do the following:
+
./bin/epadmin update ARCHIVEID
  
  
−
If this is confusing see the example at the end of the page.
 
  
 +
=== EPrints 3.1+ ===
  
−
ALTER TABLE archive ADD ''newfieldname'' ''type'' default NULL AFTER ''prevfield'';
+
EPrint 3.3's ''update'' is a synonym of the ''update_database_structure'' method available from Eprints 3.1+:
−
ALTER TABLE buffer ADD ''newfieldname'' ''type'' default NULL AFTER ''prevfield'';
 
−
ALTER TABLE inbox ADD ''newfieldname'' ''type'' default NULL AFTER ''prevfield'';
 
−
ALTER TABLE deletion ADD ''newfieldname'' ''type'' default NULL AFTER ''prevfield'';
 
  
−
==== Step 3b - Adding a "multiple" field ====
+
./bin/epadmin update_database_structure ARCHIVEID
  
−
Multiple fields need their own table, so the syntax is different.
 
  
−
Please note that these commands have been split over multiple lines for readability.
+
=== EPrints 3.0 ===
−
 
 
−
CREATE TABLE archive_''newfieldname'' ( eprintid INT NOT NULL, pos INT,
 
−
    ''newfieldname'' ''type'' default NULL, KEY eprintid (eprintid), KEY pos (pos) ); 
 
−
 
 
−
CREATE TABLE buffer_''newfieldname'' ( eprintid INT NOT NULL, pos INT,
 
−
    ''newfieldname'' ''type'' default NULL, KEY eprintid (eprintid), KEY pos (pos) );
 
−
 
 
−
CREATE TABLE inbox_''newfieldname'' ( eprintid INT NOT NULL, pos INT,
 
−
    ''newfieldname'' ''type'' default NULL, KEY eprintid (eprintid), KEY pos (pos) ); 
 
−
 
 
−
CREATE TABLE deletion_''newfieldname'' ( eprintid INT NOT NULL, pos INT,
 
−
    ''newfieldname'' ''type'' default NULL, KEY eprintid (eprintid), KEY pos (pos) ); 
 
−
 
 
−
=== Step 4 - Modify the ordervalues tables ===
 
−
 
 
−
The ordervalues table is used to store a "dumbed down" version of the value in your field used for sorting, but never rendered.
 
−
 
 
−
The same replacement values apply as for step 3 with one difference. The ''prevfield'' is the previous field in ArchiveMetadataFieldsConfig.pm even if it is a multiple field.
 
  
−
Notes:
+
To add a field to a live eprints archive in Eprints 3.0 you have to modify the SQL tables.
−
* there are two underline characters before "ordervalues".
+
Before you start this, you may wish to BackupTheDatabase.
−
* this assumes you are not running a multilanguage or non-english archive. If you ''are'' then repeat the 4 commands below and replace 'en' with each of your archive's languages in turn.
 
  
−
ALTER TABLE archive__ordervalues_en ADD ''fieldname'' TEXT AFTER ''prevfield'';
+
* Add the new columns to the appropriate tables. There are no longer four separate tables for eprints as there were in EP2 (<code>archive</code>, <code>buffer</code> etc), so it's simpler.
−
ALTER TABLE buffer__ordervalues_en ADD ''fieldname'' TEXT AFTER ''prevfield'';
+
** For a field defined in <code>eprint_fields.pl</code>, the tables are <code>eprint</code> and <code>eprint__ordervalues_en</code> (replacing <code>en</code> with your language as required).
−
ALTER TABLE inbox__ordervalues_en ADD ''fieldname'' TEXT AFTER ''prevfield'';
+
** For a field defined in <code>document_fields.pl</code>, you want <code>document</code> and <code>document__ordervalues_en</code>.
−
ALTER TABLE deletion__ordervalues_en ADD ''fieldname'' TEXT AFTER ''prevfield'';
+
** And so on...
 +
* The column types are the same as for EP2, ie in <code>eprint</code> you want a type appropriate to the type of your field exactly as described in the Recipe for EP2, while in <code>eprint__ordervalues_en</code> you want <code>text</code> irrespective of your field type.
  
−
=== Step 5 - Checking it works... ===
 
  
−
It should all be OK at this point, but it's worth checking. I suggest running generate_views on the archive to make sure it all works OK.
+
=== EPrints 2.x ===
  
−
=== Step 6 - Finishing up ===
+
See historical versions of this wiki page.
−
 
 
−
Add the config to metadata-types.xml and phrases.xml - see AddingFields
 
−
 
 
−
=== Step 7 - Restart apache ===
 
−
 
 
−
Everything should now be OK. restart the webserver
 
−
 
 
−
----
 
−
 
 
−
== Examples (for Eprints 2.x) ==
 
−
 
 
−
 
 
−
=== Normal set field example ===
 
−
To add a field of type 'set' to eprints. We add this to ArchveMetadataFieldsConfig.pm
 
−
 
 
−
{ name => "foo", type => "set", input_rows => 1,
 
−
        options => [ "yesod", "hod", "chesed" ] },
 
−
 
 
−
The previous field is a (non-multiple) text field called 'bar')
 
−
 
 
−
then run the following SQL statements:
 
−
 
 
−
ALTER TABLE archive ADD foo VARCHAR(255) default NULL AFTER bar;
 
−
ALTER TABLE buffer ADD foo VARCHAR(255) default NULL AFTER bar;
 
−
ALTER TABLE inbox ADD foo VARCHAR(255) default NULL AFTER bar;
 
−
ALTER TABLE deletion ADD foo VARCHAR(255) default NULL AFTER bar;
 
−
 
 
−
ALTER TABLE archive__ordervalues_en ADD foo TEXT AFTER bar;
 
−
ALTER TABLE buffer__ordervalues_en ADD foo TEXT AFTER bar;
 
−
ALTER TABLE inbox__ordervalues_en ADD foo TEXT AFTER bar;
 
−
ALTER TABLE deletion__ordervalues_en ADD foo TEXT AFTER bar;
 
−
 
 
−
 
 
−
 
 
−
== Recipe (for Eprints 3.x) ==
 
−
 
 
−
This is much the same as for Eprints 2.x except that the names have been changed to protect the innocent.
 
−
 
 
−
* Define your new fields in <tt>archives/ARCHIVEID/cfg/cfg.d/eprint_fields.pl</tt> for EPrint-level metadata, <tt>.../document_fields.pl</tt> for document-level metadata (this file doesn't exist by default, but is honoured), <tt>.../user_fields.pl</tt> for user metadata, etc etc.
 
−
 
 
−
=== EPrints 3.0 ===
 
−
 
 
−
* Add the new columns to the appropriate tables. There are no longer four separate tables for eprints as there were in EP2 (<tt>archive</tt>, <tt>buffer</tt> etc), so it's simpler.
 
−
** For a field defined in <tt>eprint_fields.pl</tt>, the tables are <tt>eprint</tt> and <tt>eprint__ordervalues_en</tt> (replacing <tt>en</tt> with your language as required).
 
−
** For a field defined in <tt>document_fields.pl</tt>, you want <tt>document</tt> and <tt>document__ordervalues_en</tt>.
 
−
** And so on.
 
−
* The column types are the same as for EP2, ie in <tt>eprint</tt> you want a type appropriate to the type of your field exactly as described in the Recipe for EP2 above, while in <tt>eprint__ordervalues_en</tt> you want <tt>text</tt> irrespective of your field type.
 
−
 
 
−
=== EPrints 3.1+ ===
 
−
 
 
−
Once you have added your new field definitions to the appropriate configuration file you can run the update_database_structure epadmin method from the shell:
 
−
 
 
−
./bin/epadmin update_database_structure ARCHIVEID
 

Latest revision as of 17:24, 17 July 2023


EPrints 3.3+

Follow the instructions as you would for HOW TO: Add a New Field.

As described there, you define your new fields in...

  • /opt/eprints3/archives/ARCHIVEID/cfg/cfg.d/eprint_fields.pl for EPrint-level metadata,
  • /opt/eprints3/archives/ARCHIVEID/cfg/cfg.d/document_fields.pl for document-level metadata (this file doesn't exist by default, but is honoured),
  • and /opt/eprints3/archives/ARCHIVEID/cfg/cfg.d/user_fields.pl for user metadata, etc etc.


Since a repository's eprint_fields.pl will override a flavour's eprint_fields.pl based on them both having the same file name, should you only wish to add to a flavour's fields rather than replace them, you may prefer to give your archive's local version a file name such as eprint_fields_local.pl, and then inside have only your new field(s): 

push @{$c->{fields}->{eprint}},

{
	name => 'my_first_new_field',
	type => 'set',
	options => [
	    'yes',
	    'no',
	    'partial',
	],
	input_rows => 1,
},

{
	name => 'my_second_new_field',
	type => 'set',
	options => [
	    'yes',
	    'no',
	    'partial',
	],
	input_rows => 1,
},

;


Simply make sure your push, is adding your field to the correct dataset you wish to add fields to - in this case an eprint dataset.


Then, once you have added your new field definitions to the appropriate configuration file you can run update via epadmin from the shell.


You can begin with a dry run to see what would happen: 

./bin/epadmin update_dry_run ARCHIVEID

Then once confident proceed for real: 

./bin/epadmin update ARCHIVEID


EPrints 3.1+

EPrint 3.3's update is a synonym of the update_database_structure method available from Eprints 3.1+: 

./bin/epadmin update_database_structure ARCHIVEID


EPrints 3.0

To add a field to a live eprints archive in Eprints 3.0 you have to modify the SQL tables. Before you start this, you may wish to BackupTheDatabase.

  • Add the new columns to the appropriate tables. There are no longer four separate tables for eprints as there were in EP2 (archive, buffer etc), so it's simpler.
    • For a field defined in eprint_fields.pl, the tables are eprint and eprint__ordervalues_en (replacing en with your language as required).
    • For a field defined in document_fields.pl, you want document and document__ordervalues_en.
    • And so on...
  • The column types are the same as for EP2, ie in eprint you want a type appropriate to the type of your field exactly as described in the Recipe for EP2, while in eprint__ordervalues_en you want text irrespective of your field type.


EPrints 2.x

See historical versions of this wiki page.

Retrieved from ‘https://wiki.eprints.org/w/index.php?title=Adding_a_Field_to_a_Live_Repository&oldid=16083’