Selected Database Tables
========================

<toc/>

<style>
table { border-collapse: collapse; }
table tr td {
 vertical-align: top;
 padding: .8ex;
}
table tr td,
table tr th {
 border: 1px solid #ccc;
}
.red { color: #911; font-style:italic; }
</style>


ACIS creates and maintains a number of database tables.
These tables are needed for system's work, but can be used
for additional purposes.

<h2 id='records-table'>Records table</h2>

Contains basic information about each personal record
currently maintained through the system.  Database name: as
configured in main.conf via <c>acis-db-name</c>, table name:
<var>records</var>.

Columns: shortid, id, owner, userdata\_file, namelast,
namefull, profile\_url, emailmd5.



<table valign='top'>

<tr>
<th>column</th>
<th>type</th>
<th>description</th>
</tr>

<tr>
<td>shortid</td>
<td>char(10) not null primary key</td>
<td>record's short-id</td>
</tr>

<tr>
<td>id</td>
<td>char(130) not null</td>
<td>record's identifier</td>
</tr>

<tr>
<td>owner</td>
<td>char(110) not null</td>
<td>login name (email address) of the user, who owns the
record; shall not be accessible to the outside world</td>
</tr>

<tr> <td>userdata_file</td> <td>char(200) binary not null</td>
<td>full absolute path to the userdata file, where the
record is stored; shall not be accessible to the outside
world</td> </tr>

<tr>
<td>namelast</td>
<td>char(70) not null</td>
<td>name of the person in the form "Lastname, Firstname"
with optional middle name and suffix following</td>
</tr>

<tr> <td>namefull</td> <td>char(70) not null</td> <td>full
name of the person as user entered it on the name screen;
usually "Firstname Middlename Lastname"</td> </tr>

<tr>
<td>profile_url</td>
<td>char(100) binary not null default \"\"</td>
<td>absolute URL of the personal profile page (on the site of the installation)</td>
</tr>

<tr>
<td>homepage</td>
<td>char(130) binary not null default \"\"</td>
<td>URL of the personal homepage, if known</td>
</tr>

<tr>
<td>emailmd5</td>
<td>char(16) binary not null default \"\"</td>
<td>128 bit MD5 digest of the person's email in lower case, if it is
known; empty string otherwise.  Calculated as:

<blockquote><code><pre>
require Digest::MD5;
my $emailmd5 = Digest::MD5::md5( lc $email );
</pre></code></blockquote>

</td>
</tr>


</table>




<h2 id='names-table'>Names table</h2>

Contains name variations of each personal record currently
maintained through the system.  Database name: as configured
in main.conf via <c>acis-db-name</c>, table name: <var>names</var>.

Columns: shortid, name, probability.


<table valign='top'>

<tr>
<th>column</th>
<th>type</th>
<th>description</th>
</tr>

<tr>
<td>shortid</td>
<td>char(10) not null</td>
<td>record's short-id</td>
</tr>

<tr>
<td>name</td>
<td>char(100) not null</td>
<td>personal name variation</td>
</tr>

<tr>
<td>probability</td>
<td>tinyint unsigned not null</td>
<td>reserved for future use; currently always
equals 255
</td>
</tr>

</table>

An index:  <code> PRIMARY KEY ( shortid, name ) </code>




## Misc


<h3 id='pidaid-db-expose'>How to expose ACIS database for Person Identification
Aid</h3>


This is needed to allow a document submission service <a
href='cooperate.html#level3'>to search the personal records
database</a> (and offer matching items for user to select).

Given the fact that ACIS uses MySQL for database, and MySQL
is a network-capable system, and includes an
authorization/authentication subsystem, it's most simple to
use these features.  It is in the power of the ACIS
administrator to make a particular database table accessible
to another user on the net.  

To open access to the needed database tables, ACIS
administrator have to:

  1. Configure his MySQL server to listen to a network TCP
  port on the machine; ensure the server port is accessible
  from the submission service machine.  (May involve changes to a
  firewall configuration.)  

  Usual default configuration of MySQL enables TCP network
  access on port 3306.  You may check or change it in your
  <f>/etc/my.cnf</f> or <f>/etc/mysql/my.cnf</f> file.

  2. Create a new MySQL user with a password for a
  submission service to use.  Give to this new user SELECT
  privilege on certain fields of the records table and on
  the names table.  Here is what statements to run:

  <pre><code>GRANT SELECT (shortid,id,namelast,namefull,profile_url,homepage,emailmd5)
      ON <span class='red'>acisDatabase</span>.records
      TO <span class='red'>frank@eprints.super.edu</span> IDENTIFIED BY "<span class='red'>goblin</span>";</code>
  </pre>
  
  <pre><code>GRANT SELECT
      ON <span class='red'>acisDatabase</span>.names
      TO <span class='red'>frank@eprints.super.edu</span>;</code>
  </pre>
     
  <pre><code>FLUSH PRIVILEGES;</code>
  </pre>

  Here <code><span class='red'>acisDatabase</span></code> is
  the database name (the <c>acis-db-name</c> parameter in
  main.conf), <code><span
  class='red'>frank@eprints.super.edu</span></code> is the
  name of the user and its hostname (name of the host from
  which it will contact our database), <code><span
  class='red'>goblin</span></code> is its password.  You can
  run these statements in MySQL's <code>mysql</code>
  terminal utility.  You will need administrator's
  privileges.


  If the above does not work, and you can't get database
  connected (error message "Client does not support
  authentication protocol requested by server; consider
  upgrading MySQL client"), read <a
  href='http://dev.mysql.com/doc/mysql/en/password-hashing.html'>that</a>.
  Depending on your MySQL server version and client
  libraries your remedy may be in these statements:

  <pre><code>UPDATE mysql.user SET Password = OLD_PASSWORD('<span class='red'>goblin</span>')
      WHERE Host = '<span class='red'>eprints.super.edu</span>' AND User = '<span class='red'>frank</span>';</code>
  </pre>

  <pre><code>FLUSH PRIVILEGES;</code>
  </pre>
  
  

  3. Send the hostname (local host where ACIS and MySQL are
  installed), the port number (e.g. 3306), the database name
  (e.g. <code><span class='red'>acisDatabase</span></code>),
  the user name (e.g. <code><span
  class='red'>frank</span></code>), the password
  (e.g. <code><span class='red'>goblin</span></code>) to the
  submission service administrator.  (These items are
  collectively referred to as "MySQL access parameters" in
  <a href='http://acis.openlib.org/documents/saskatoon/'>Saskatoon</a> doc.)



Relevant pieces of MySQL documentation online:

   - <a href='http://dev.mysql.com/doc/mysql/en/using-mysql-programs.html' >Using MySQL Programs</a>

   - <a href='http://dev.mysql.com/doc/mysql/en/configuring-mysql.html' >Configuring the MySQL Server</a>

   - <a href='http://dev.mysql.com/doc/mysql/en/privilege-system.html' >The MySQL Access Privilege System</a>
   
      - <a href='http://dev.mysql.com/doc/mysql/en/privileges.html' >How the Privilege System Works</a>
      - <a href='http://dev.mysql.com/doc/mysql/en/password-hashing.html' >Password Hashing in MySQL 4.1</a>

   - <a href='http://dev.mysql.com/doc/mysql/en/user-account-management.html' >MySQL User Account Management</a>

      - <a href='http://dev.mysql.com/doc/mysql/en/adding-users.html' >Adding New User Accounts to MySQL</a>
      - <a href='http://dev.mysql.com/doc/mysql/en/passwords.html' >Assigning Account Passwords</a>

   - <a href='http://dev.mysql.com/doc/mysql/en/account-management-sql.html' >Account Management Statements</a>

      - <a href='http://dev.mysql.com/doc/mysql/en/grant.html' >GRANT and REVOKE Syntax</a> 





