View source for Using Internal IDs for Staff Browse Views

== Scenario ==
Your institution/organisation has a unique identfiers for your members/staff and you want to be able to use these to create a browse view listing each individuals publication list.

By default EPrints provides a browse view based on the given name and family name of those listed in the Creators field of an EPrints publication.  This is not useful for most institutions/organisations for a number of reasons:
# Given name and family name is not necessary unique
# Some creators will not be members of your institution/organisation and therefore you do not want them listed.
# You have an existing ID that you want to be able to use programmatically to link to their EPrints publication list.

== Solution ==
By default, when adding creators to an EPrint, as well as a field for given name and family name there is also a column for '''Email''', this is just labelled as such but is actually named '''creators_id''' and therefore can be any unique identifier for the user.  However, it is important that the unique identifier used is consistent, (i.e. it is always an email address or another unique identifier used by your institution/organisation).  In general, it is best to retain email address as a unique identifier, as you may wish to use this to allow visitors to you repository to contact creators (authors), also you may want to record the email address of creators who are not part of your institution/organisation.  Therefore for this solution, we will assume that another unique identifier will be used separate to email address.

Lets assume that your institution/organisation has a public members/staff ID that you want to use.  To ensure that this members/staff ID is adding whenever this person is added as a creator, you can use  [[Autocompletion]].  Autocompletion can be setup to use the users records within EPrints.  This assumes that you have generated accounts for all your members/staff.  This can often be done using [[LDAP]].

== Procedure ==
'''N.B.''' The following instructions assume EPrints has been installed in the directory '''/opt/eprints3/''' some EPrints install will appear under '''/usr/share/eprints3/''' or other locations.  Make sure you amend these as appropriate for your instaltion

=== Add Internal ID field to User ===
1. In your archive's '''cfg/cfg.d/user_fields.pl''' file ad the following snippet of code at the end:

 push @{$c->{fields}->{user}},
 {
   name => 'internalid',
   type => 'id',
 };

2. Run EPrints database update command to add this new field:

 /opt/eprints3/bin/epadmin update ARCHIVENAME

3. Assuming the above has been successful add the phrases required for this new field to '''cfg/lang/en/phrases/local.xml'''

 <epp:phrase id="user_fieldname_internalid">Internal ID</epp:phrase>
 <epp:phrase id="user_fieldhelp_internalid">Unique ID used to identify a user, used by <epc:phrase ref="archive_name" /></epp:phrase>

4. Test that EPrints is happy with these changes and if so reload Apache:
 /opt/eprints3/bin/epadmin test ARCHIVENAME
 apachectl graceful


=== Add Internal ID to creators/editors/contributors fields for an EPrint ===
1. Add the following code the a file at '''/opt/eprints3/lib/plugins/EPrints/MetaField/Internalidname.pm''':

 package EPrints::MetaField::Internalidname;
 
 use strict;
 use warnings;
 
 use EPrints::MetaField::Text;
 
 BEGIN
 {
   our( @ISA );
   @ISA = qw( EPrints::MetaField::Text );
 }
 
 sub _get_name
 {
   my( $self, $session, $internalid ) = @_;
 
   my $format = $session->config( 'internalid_to_name', 'format' );
 
   return unless defined $format;
 
   if( $session->can_call( 'internalid_to_name', 'parser' ) )
   {
     my $name = $session->call( [ 'internalid_to_name', 'parser' ], $session, $internalid );
     return $session->render_name( $name, $format ) if defined $name;
   }
 
   return;
 }
 
 sub get_value_label
 {
   my( $self, $session, $value ) = @_;
 
   my $name = $self->_get_name( $session, $value );
   return $name if defined $name;
 
   return $session->make_text( $value );
 }
 
 sub ordervalue_basic
 {
   my( $self, $value, $session, $langid ) = @_;
 
   my $name = $self->_get_name( $session, $value );
   return EPrints::Utils::tree_to_utf8( $name ) if defined $name;
  
   return $value;
 }
 
 sub render_single_value
 {
   my( $self, $session, $value ) = @_;
   return $self->get_value_label( $session, $value );
 }
 
 1;

2. Edit your archive's '''cfg/cfg.d/eprint_fields.pl'''.  Under the field named '''creators''', you will see a block labelled '''fields'''.  Copy and paste the block that has the '''sub_name''' '''id''' and copy and paste it just before the end '''fields''' block, ensuring to add a comma a comma prior to this.  Then modify the '''sub_name''  from '''id''' to ''internalid'''.  The creators block should then look something like below:

 {
   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 => 'internalid',
       type => 'internalidname',
       input_cols => 10,
       allow_null => 1,
       render_single_value => 'render_internalid',
     },
   ],
 },

3. Repeat this change with the '''contributors''' and '''editors'' fields.


4. Create a file called '''internalid_to_name.pl''' in '''cfg/cfg.d/''' of your archive, with the following contents:

 $c->{internalid_to_name}->{parser} = sub
 {
   my( $session, $internalid ) = @_;
   return unless EPrints::Utils::is_set( $internalid );
 
   my $user_ds = $session->get_repository->get_dataset( "user" );
   my $user_search = new EPrints::Search( session => $session, dataset => $user_ds );
   $user_search->add_field( $user_ds->get_field( "internalid" ), $internalid );
   my $users = $user_search->perform_search;
   return unless $users->count() > 0;
 
   return $users->item( 0 )->get_value("name");
 };
 
 $c->{internalid_to_name}->{format} = 0; # family, given
 
 $c->{render_internalid} = sub
 {
   my( $session, $field, $value, $obj ) = @_;
 
   my $fragment = $session->make_doc_fragment;
   $fragment->appendChild($session->xml->create_text_node($value));
   return $fragment;
 }

5. Run EPrints database update command to add these new sub-fields:

 /opt/eprints3/bin/epadmin update ARCHIVENAME 

6. Assuming the above has been successful add the phrases required for this new field to '''cfg/lang/en/phrases/local.xml'''

 <epp:phrase id="eprint_fieldname_creators_internalid">Internal ID</epp:phrase>
 <epp:phrase id="eprint_fieldhelp_creators_internalid">Unique ID used to identify a user, used by <epc:phrase ref="archive_name" /></epp:phrase>
 <epp:phrase id="eprint_fieldname_contributors_internalid">Internal ID</epp:phrase>
 <epp:phrase id="eprint_fieldhelp_contributors_internalid">Unique ID used to identify a user, used by <epc:phrase ref="archive_name" /></epp:phrase>
 <epp:phrase id="eprint_fieldname_editors_internalid">Internal ID</epp:phrase>
 <epp:phrase id="eprint_fieldhelp_editors_internalid">Unique ID used to identify a user, used by <epc:phrase ref="archive_name" /></epp:phrase>

7. Test that EPrints is happy with these changes and if so reload Apache:
 /opt/eprints3/bin/epadmin test ARCHIVENAME
 apachectl graceful


=== Add Autocompletion for creators/editors/contributors fields ===
1. Create a new file in your archive under '''cgi/users/lookup/staffinternal''' and edit:

 use EPrints;
 use strict;
 
 my $session = EPrints::Session->new();
 
 my $content = "text/xml";
 $session->send_http_header( content_type=>$content );
 my $family = $session->param( "_name_family" );
 my $given = $session->param( "_name_given" );
 my $id = $session->param( "_id" );
 my $internalid = $session->param( "_internalid" );
 
 my $database = $session->get_database;
 my $dataset = $session->get_repository->get_dataset( "user" );
 my $name_field = $dataset->get_field( "name" );
 my $email_field = $dataset->get_field( "email" );
 my $internalid_field = $dataset->get_field( "internalid" );
 
 # the field to use as the creator ID
 my $id_fieldname = "email";
 my $id_field = $dataset->get_field( $id_fieldname );
 
 my @fields = ($name_field->get_sql_names, $id_field->get_sql_names, $email_field->get_sql_names, $internalid_field->get_sql_names);
 
 my $Q_table = $database->quote_identifier($dataset->get_sql_table_name);
 my $Q_usertype = $database->quote_identifier( "usertype" );
 my $Q_id = $database->quote_identifier( $id_fieldname );
  
 my $sql = "SELECT " . join(",", map { $database->quote_identifier($_) } @fields ) .
   " FROM $Q_table " .
   " WHERE $Q_usertype != ".$database->quote_value( "minuser" ) .
   " AND $Q_id IS NOT NULL ";
 
 if( EPrints::Utils::is_set( $family ) )
 {
   $sql .= " AND ".$database->quote_identifier("name_family").$database->sql_LIKE().$database->quote_value(EPrints::Database::prep_like_value($family).'%');
 }
 if( EPrints::Utils::is_set( $given ) )
 {
   $sql .= " AND ".$database->quote_identifier("name_given").$database->sql_LIKE().$database->quote_value(EPrints::Database::prep_like_value($given).'%');
 }
 if( EPrints::Utils::is_set( $id ) )
 {
   $sql .= " AND ".$database->quote_identifier($id_field->get_name).$database->sql_LIKE().$database->quote_value(EPrints::Database::prep_like_value($id).'%');
 }
 if( EPrints::Utils::is_set( $internalid ) )
 {
   $sql .= " AND ".$database->quote_identifier($internalid_field->get_name).$database->sql_LIKE().$database->quote_value(EPrints::Database::prep_like_value($internalid).'%'); 
 }
 
 $sql .= " ORDER BY " .
   $database->quote_identifier("name_family").",".
   $database->quote_identifier("name_given");
 
 my @rows;
 
 my $sth = $session->get_database->prepare_select( $sql, 'limit' => 40 );
 $session->get_database->execute( $sth , $sql );
 while( my @row = $sth->fetchrow_array )
 {
   my $name = $name_field->value_from_sql_row( $session, \@row );
   my $email = $email_field->value_from_sql_row( $session, \@row );
   my $id = $id_field->value_from_sql_row( $session, \@row );
   my $internalid = $internalid_field->value_from_sql_row( $session, \@row );
 
   my $item = {};
   push @rows, $item;
 
   my $frag = $session->make_doc_fragment;
   $frag->appendChild( $name_field->render_single_value( $session, $name ) );
   if ( EPrints::Utils::is_set( $internalid ) ) 
   {
     $frag->appendChild( $session->make_text( " [" ) );
     $frag->appendChild( $email_field->render_single_value( $session, $internalid ) );
     $frag->appendChild( $session->make_text( "]" ) );
   }
   if ( EPrints::Utils::is_set( $email ) ) 
   {
     $frag->appendChild( $session->make_text( " (" ) );
     $frag->appendChild( $email_field->render_single_value( $session, $email ) );
     $frag->appendChild( $session->make_text( ")" ) );
   }
   
   $item->{xhtml} = $frag;
   $item->{values} = [
     "for:value:relative:_name_family" => $name->{family},
     "for:value:relative:_name_given" => $name->{given},
     "for:value:relative:_name_honourific" => $name->{honourific},
     "for:value:relative:_name_lineage" => $name->{lineage},
     "for:value:relative:_internalid" => $internalid,
     "for:value:relative:_id" => $id,
   ];
 }
 
 $sth->finish();
 my $ul = EPrints::Extras::render_lookup_list( $session, \@rows );
 $session->send_http_header( content_type => "text/xml; charset=UTF-8" );
 binmode(STDOUT,":utf8");
 print <<END;
 <?xml version="1.0" encoding="UTF-8" ?>
 
 END
 print EPrints::XML::to_string( $ul, "utf-8", 1 );
 EPrints::XML::dispose( $ul );
 $session->terminate;


2. Edit your archive's '''cfg/workflows/eprint/default.xml''' and replace '''/users/lookup/name''' with '''/users/lookup/staffinternal''' where it appears as the '''input_lookup_url''' for '''creators''', '''editors''', and '''contributors'''.  N.B. each of these fields may appear more than once in this file due to the use of conditional statements.

3. Now test the configuration and although it should not be necessary ,it is worth gracefully reloading Apache to make sure the latest configuration is loaded.
 /opt/eprints3/bin/epadmin test ARCHIVENAME
 apachectl graceful

=== Create Browse View based on Internal IDs ===
1. Edit your archives '''cfg/cfg.d/views.pl''' and add the following code snippet at the end of the file:

 push @{ $c->{browse_views} }, (
 {
   id => "creators_internalid",
   allow_null => 0,
   hideempty => 1,
   menus => [
     {
       fields => [ "creators_internalid", "contributors_internalid", "editors_internalid"  ],
       new_column_at => [1, 1],
       mode => "sections",
       open_first_section => 1,
       group_range_function => "EPrints::Update::Views::cluster_ranges_30",
       grouping_function => "EPrints::Update::Views::group_by_a_to_z",
     },
   ],
   order => "-date/title",
   variations => [
     "type",
     "date;truncate=4,reverse",
     "DEFAULT",
   ],
 });

2. Add the following phrase to your archives's '''cfg/lang/en/phrases/local.xml''':

 <epp:phrase id="viewname_eprint_creators_internalid">Internal Creators</epp:phrase>

3. Test that EPrints is happy with these changes and if so reload Apache:
 /opt/eprints3/bin/epadmin test ARCHIVENAME
 apachectl graceful

4. Request the path '''/views/creators_internalid''' under your repository's hostname in a web browser (e.g. http://example.eprints.org/views/creators_internalid).