ACIS administrator's guide
==========================

<toc/>


Other related files:

 - <a href='conf.html'>Configuration guide</a>
 - <a href='apache-conf.html'>Apache configuration and URLs of ACIS</a>



<h2 id='utils'>Utilities in <f>{HOME}/bin/</f></h2>


<c>bin/setup</c> -- update system's configuration.


### <C>bin/create_tables</C> script

<co>bin/create_tables</co> creates MySQL tables for ACIS.
If a table exists already, it will not delete it.  If you
want to force re-creating the tables, give it
<code>-f</code> command-line switch.


### <C>bin/backup_tables</C> script

Usage: 

    bin/backup_tables [database table1 table2 ...]

<co>bin/backup_tables</co> creates backups of the specified
tables from the specified database.  If no database and no
tables are specified, it backups most important tables from
the ACIS database.  Currently these are:

    acis.sysprof acis.suggestions acis.cit_suggestions
    sid.sid_id_to_handle sid.sid_last_numbers

"acis" and "sid" here stand for your configuration values
<c>acis-db-name</c> and <c>sid-db-name</c> respectively if they are
defined, or <c>db-name</c> if they are not.

A directory is created for the backup files, based on
<c>backup-directory</c> and the current date.  For example,
if <c>backup-directory</c> is set to "/opt/ACIS/backup", and
executed on 1 September 2006, it would be:
"/opt/ACIS/backup/2006/09/01/".  The <c>backup-directory</c>
must exist already, but its subdirectories will be created
if the do not exist.

To be able to use this utility, ACIS mysql user must have
<tt>FILE</tt> and <tt>LOCK TABLES</tt> privileges on the
server. 

You don't have to shut down the service to create backups
with this utility.


### <C>bin/restore\_table\_backup</C> script

Usage: 

    bin/restore_table_backup backup_file [...]

Restores one or several backups previously created by
<c>bin/backup_tables</c>.  


### <C>bin/rid</C> script

<co>bin/rid start</co> starts and <co>bin/rid stop</co> 
stops the <a ref='ri-daemon'>update daemon</a>.
<co>bin/rid restart</co> stops and then re-starts it.



### <C>bin/updareq</C> script

<dl>

<dt><co>bin/updareq COLLECTION PATH [TOO_OLD]</co></dt>

<dd>Sends an update request to the <a
href='#ri-daemon'>update daemon</a>.  It asks to update file
or dir <co>PATH</co> in collection <co>COLLECTION</co>.
<co>TOO_OLD</co> is time in seconds.  If a file was last
time processed more than <co>TOO_OLD</co> seconds ago, the
daemon will process it again (even if it didn't change
since).  By default, <co>TOO_OLD</co> is
<code>86400*12</code> seconds, which means 12 days.  </dd>

</dl>

Read more about the updates in <a href='#ri-daemon'>update
daemon section</a>.

If the script fails to send a request, it will complain.



### <C>bin/sid_base</C> script


The <a ref='short-ids'>short-id</a> database management utility.

<dl>

<dt><co>bin/sid_base clear</co></dt>

<dd>Will initialize the database, (re-)creating the
tables.</dd>


<dt><co>bin/sid_base backup</co></dt>

<dd>Will make a backup copy of appropriate table files in
<f>{HOME}/SID/backup/YYYY/MM-DD/</f> directory, where
<co>YYYY</co>, <co>MM</co> and <co>DD</co> are current year,
month and day number.</dd>

<dt><code>bin/sid_base import <i>file</i></code></dt>

<dd>Will import short-id => identifier pairs from the log
file <i>file</i>.</dd>

<dt><code>bin/sid_base import-dup <i>file</i></code></dt>

<dd>Will do the same without complaining about duplicate
itentifiers.</dd>

</dl>



### <C>bin/clean-up</C> script

Expired sessions cleaner.  Will go through session files in
<f>{HOME}/sessions/</f>, look into each file, check
how old it is and what session type it is and will close the
session if its time has come.

A new-user session's time has come if it is a week old.
Such sessions are wiped out without regret.

A regular user session's time has come if it is older than
<c>session-lifetime</c> seconds, as specified in
configuration.  When closing a regular user session, her
data (possibily changed) will be saved and her profile page
will be updated.

ACIS needs this script for normal operation.  Run it
regularly, e.g. by a cron-job.  As it prints out some
information about each session it looks at, you better
capture its output into a log file.  For example

    */11 * * * * /home/user/acis/bin/clean-up >> /home/user/acis/clean-up.log


### <co>bin/apu</co> script

See <c>bin/apu</c>.


### <C>bin/events_archiving</C> script

The script incrementally processes the <a
ref='events-database'>events database</a>, which is an
alternative logging method, used by ACIS.  The nature of the
database makes it difficult (slow and expensive) to browse
through older events.  This script packs session data into a
single database row, thus making access to this data via the
<c>/adm/events</c> screen quicker.

It makes sense to configure a cronjob to run this script
once a day or once a week.





<h2 id='short-ids'>The short-ids</h2>


Short-ids are short unique alpha-numeric identifiers, that
ACIS assigns to the personal and other records.  They are
used in ACIS extensively and must stay unique and persistent
and designed for this.  The short-ids are also used as
shorter aliases for the longer external identifiers.  There
is a strict one-to-one relationship between each short-id
and its longer counter-part.

The assigned short-ids are kept in the short-id database and
logged into <f>SID/short-id.log</f>.






Logging.  Tracking and debugging problems
-----------------------------------------


ACIS is a complicated software and keeps a number of
different logs.  Each subsystem maintains its own log, and
sometimes -- several logs.  The logs give you capability to
see what is going on and to track problems, if any.  <a
ref='installation-files' >Below in another section</a> there
is a list of files in an installation of ACIS, including the
logs.  Here is a description of what is logged and into
which files.


### Web interface and users' interactions

The users' interactions with the system are logged into the
<f>acis.log</f> file.  This is the main log, which shows
what users were or are doing with the system.  Problems and
errors that happen during these interactions are
additionally logged to the <f>acis-err.log</f> file.

Additionally, all the interactions are stored into the
<i>events</i> database.  This database is browsable online
via the <a ref='adm-events'>/adm/events</a> screen.

Each incoming request may be logged into so-called
requests-log; this is disabled by default, but is governed
by the <c>requests-log</c> configuration parameter.  It is a
brief log and it only contains the trailing URL part of the
request, and it should give you an idea about which screen
the request was for.

Also, it is important to monitor the web-server's error log.
If something doesn't work well in ACIS, and its code crashes
unexpectedly before even being able to handle the request or
during that, only the web-server's logs will contain info
and details about the problem.

In case of real problems of ACIS web interface misbehaving,
the "debuggings" log may get useful.  To enable it set the
<c>debug-log</c> parameter in main.conf to a file name.  For
each incoming request handled by ACIS, it will contain a
detailed trace of everything what happens internally.  One
request may generate about 15-25 lines of processing
details, sometimes even much more than this.  But note that
it will slow things down considerably and will eat your
diskspace quickly.






### Automatic profile update (APU)

APU-related activity (see <c>bin/apu</c>) is logged into the
<f>autoprofileupdate.log</f> file.


### Background searches for documents and other resources

When a user enters hers research profile after a while or
after she changes her name variations, ACIS runs an
automatic search for research.  APU processing for a record
also runs this search.  In both cases it is run in the
background, not under the web-server process, as the CGI
requests are.  So it is logged into a separate log--the
<f>back.log</f> file.  It shows which name variations where
searched and how many matching items were found.


### Sessions

Sessions are created by the web interface of ACIS, and so it
is usually logged together with other events of the web
interface.  But the abandoned or left sessions are taken
care of by the <c>bin/clean-up</c> script.  It closes the
expired sessions, saving the changes to the user's accounts,
if necessary.  And while it does not itself write a log, we
recommend that you configure the cronjob to redirect its
output into the <f>clean-up.log</f> file.

But if you need to check the currently active sessions and,
possibly, to peek into one of them, use the
<c>/adm/sessions</c> administrator's screen.



### Metadata processing


Metadata is processed by the <a href='daemon.html'>update
daemon</a> and the update daemon writes several logs.  One
log is general and covers the update requests coming from
applications (including ACIS' web interface) and utilities
(<c>bin/updareq</c>).  It documents the essential details of
each request: the collection id, the path to update, the
<co>TOO_OLD</co> parameter and, of course, time of the
request.  Then it logs the channel number.  All that is in
the <f>RI/daemon.log</f> file.

There are 5 channels in the update daemon and they run in
parallel.  Each channel is processing one request at any
given time, if any at all.  If all 5 channels are busy and a
new request comes in, it would have to wait till one of the
channels becomes available.

<p>Each of the channels has its own logfile.  These are named
from <f>RI/update_ch0.log</f> for channel no. 0 through
<f>RI/update_ch4.log</f> for channel no. 4.  A channel's log
includes all the details of the requests taken and the
processing details.  If any problems or errors happen during
processing, they would normally be reported to the channel's
log.</p>

The actual metadata processing also involves ARDB.  That
work is logged into the <f>ardb.log</f> file.


### The log of short-ids 

All created and assigned <a ref='short-ids'>short-ids</a>
are logged into the <f>SID/short-id.log</f>.

This log can be used to recreate the short-ids database, see
<c>bin/sid_base</c> script.



### MySQL log

If an SQL query or a statement fails, it is logged into the
<f>sql.log</f> file, with all the details.  Normally this
log will only contain messages about database connections
having been established or re-established.


### Archiving and rotating the logs

For an actively used service the amounts of logs generated
is great and no matter how big your harddrive is, one day
they will fill it up.  To avoid it and to stop worrying
about it, we recommend configuring log rotation with the
logrotate tool.

Here is how your <f>logrotate.conf</f> file could look like:

    compress
 
    /home/user/ACIS/*.log /home/user/ACIS/RI/daemon.log /home/user/ACIS/RI/ri.log {
      rotate 300
      olddir /home/user/ACIS/oldlog/
      daily
      copytruncate
      delaycompress
    }


If the version of logrotate you have supports <co>dateext</co>
directive, you may use that as well.

You will probably want to rotate your web-server's logs in a
similar fashion.



<h3 id='events-database'>The events database</h3>


The events database is an alternative to the <f>acis.log</f>
file.  It contains data and details about what happened to
your ACIS service over time.  But it is not a text file as
the usual logs are, but it is a MySQL database table with a
number of columns for capturing different kinds of events in
detail.  You can browse that table with your favorite MySQL
database management tool, like PHPMyAdmin (the table is
surprisingly named "events"), but some details will be
hidden from you because of the data packing method used.  So
we suggest to use the <c>/adm/events</c> screen instead,
because it was designed for this purpose.

This screen gives you capability to see what was happening
to your ACIS on a certain hour of a certain day, and who was
registering recently, and which works did that man claim.
You can monitor things as they happen.  

The database also covers the work of some of the scripts,
like <c>bin/apu</c>, because such scripts alter the user
accounts.

Also, to keep these things usable, it helps to run the
<c>bin/events_archiving</c> script regularly (or
occasionally).  It will pack parts of the database and make
loading things from it quicker.





What to back up and how to restore
----------------------------------

### Critical data

There are two most critical things you should backup
regularly in a service: the userdata files and the short-id
log.  The <a ref='userdata'>userdata files</a> are all the
files below the <f>userdata/</f> directory in your ACIS
home.  They should be archived with all the directory
structure.  The <a ref='short-ids'>short-id</a> log is the
<f>SID/short-id.log</f> file.

You should also backup your primary metadata, but that
should be obvious.  

Also obvious, but let me say this for completeness.  In
addition to userdata, short-id log and your primary
metadata, keep a safe backup of:

<ul>

<li>your ACIS configuration file (<f>main.conf</f>),</li> 

<li>your Apache configuration,</li> 

<li>the files in the <f>site/</f> directory (see <a
ref='site'>here</a>),</li> 

<li>your local <a ref='phrases'>phrases</a> file
(<f>presentation/default/phrase-local.xml</f>)</li>

<li>a copy of your crontab file with your cronjobs</li>

<li>and all other files that you might have created and
added to your ACIS installation or modified in it.</li>

</ul>


This will make you able to reconstruct a severely damaged
service with moderate effort in moderate time.


### Other data

To allow even faster and smoother recovery after a severe
system failure with a data loss you may also keep backups of
the databases.  It is <b>optional</b>, because all the
crucial data can be reconstructed from the critical pieces
listed in the previous section.

So do this only if you have a cheap backup facility with
enough space.  In that case additionally create copies of:

<ul>

<li>the MySQL tables;</li>

<li>the <a ref='ri-daemon'>update daemon</a> database.</li>

</ul>


#### MySQL tables

See <c>bin/backup\_tables</c> and <c>bin/restore_table\_backup</c> scripts.

Consult MySQL documentation on additional ways to back up the mysql tables: <a
href='http://dev.mysql.com/doc/refman/4.1/en/backup.html'>Database Backups</a>
and all the section <a
href='http://dev.mysql.com/doc/refman/4.1/en/disaster-prevention.html' >Backup
and Recovery</a>. (These links are for MySQL version 4.1.)


#### Update daemon database

The update daemon uses Berkeley DB for storing its data.  Consult its
documentation for backup instructions: <a
href='http://www.sleepycat.com/docs/ref/transapp/archival.html'>Database and
log file archival</a>.

If you want to backup that, you should intergrate it into <a
ref='db-house'>the database housekeeping</a>.  It would be
much easier then.






### Restoring a service after a crash

Of course, how you are going to restore a service depends
greatly on what damage happened.
If you have lost the machine with all its setup, you'll
have to recreate the installation and its configuration
first.  Then restore from backups all the files that you can
restore.

1. If you have lost your MySQL tables, use
   <c>bin/create_tables</c> to recreate the database
   structure or restore the databases from your backups if
   you have them.

   If you still have the tables after the crash, check and
   try to recover them with MySQL's table integrity checking
   utilities.

1. Restore the <f>userdata/</f> directory's contents from
your backups.

1. Restore the <f>SID/short-ids.log</f> log from your
   backups.

1. Recreate the short-ids database by calling
<c>bin/sid_base</c> <code>import SID/short-ids.log</code>
command.

1. Restore your primary metadata.

1. Start the update daemon, call <c>bin/rid</c>
<co>start</co> command.

1. Make sure MySQL server is running and is configured properly.

1. Request the update daemon to process your primary
metadata, use the <c>bin/updareq</c> utility.

1. Make sure the web-server (Apache) is running and all the
cron-jobs are restored.

1. Check as much as you can to see if it all works well.




<h2 id='userdata'>Managing user accounts</h2>


The user accounts in ACIS are XML files in the
<f>{HOME}/userdata/</f> directory.  We call them _userdata_
files.  These files use <co>ACIS::Data::DumpXML</co> format,
which means such a file represents a Perl data structure.
Having it in XML means it is human-readable and -editable at
the same time.  By editing an account (i.e. a userdata) file
you directly edit the user's information, and so you have
power to change it in any way.

The <f>userdata/</f> directory has two-level structure.
Userdata file for account <co>vasya@pupkin.com</co> will be
in <f>userdata/v/a/vasya@pupkin.com.xml</f>.
"<co>v</co>" and "<co>a</co>" are the first two English
letter-characters of the user's account name (email
address).

Userdata file for each account consists of two main parts:
the user part -- <co>owner</co> element and and the records
part -- <co>records</co> element.  In XML terms, both are
children of document element <co>data</co>:

       <data>
          <owner>
             ...
          </owner>
          <records>
             ...
          </records>
       </data>

In XPath abbreviated syntax, the first is
<co>/data/owner</co> and the second is
<co>/data/records</co>.  Each of these elements has its own
purpose and structure.  Therefore below I'll call them
owner branch and records branch respectively.


<h3 id='userdata-owner'>Userdata structure: owner branch</h3>

Owner branch of a userdata file describes the account and
the user.  It's primary content are <co>login</co>,
<co>name</co>, <co>password</co> elements, whose purpose
won't be a great puzzle for you.  To make it clear,
<co>password</co> is verbatim password that the user has to
enter to enter into account, no ciphering applied.  Element
<co>name</co> contains human name of the user.

Element <co>type</co> is not neccessary.  It may contain
zero, one or many elements to specify additional privileges
of the user.  For instance, when user is supposed to manage
several personal records, she will have <co>advanced</co>
privilege, i.e. <co>advanced</co> element in <co>type</co>
element.

Administrator users will have <co>admin</co> element in
<co>type</co>; more about it <a
ref='adm-slash-access'>later</a>.

Typical owner branch of a userdata may look like this:

          <owner>
            <IP>81.25.33.145</IP>
            <last-change-date>2004-08-25 14:14:52 +0300</last-change-date>
            <login>vasya@pupkin.com</login>
            <password>ngi5Go</password>
            <name>Vasya Pupkin</name>
            <type><empty-hash /></type>
          </owner>

Order of elements in <co>owner</co> does not matter.  The
<co>IP</co> and <co>last-change-date</co> elements are added
by ACIS and updated on each user login, but not used for
anything.


<h3 id='userdata-records-personal'>Userdata structure: records branch. Personal record</h3>

The records branch contains __a list of records__, that the
user has created.  Most users only have one record in the
list.  But still this means the following structure.

       <data>
          ...
          <records>
             <list-item>
                ...
             </list-item>
             ...
          </records>
       </data>


Most usually the record in a userdata describes the same
person as the owner branch does, but technically this
doesn't have to be that way.  

The only possible record type at this stage is
<co>person</co> record type.

A person record is a hash in perl terms.  In XML terms it is
an unordered list of elements, which cannot be repeated.
Elements <co>id</co>, <co>type</co>, <co>sid</co> represent
the record's identifier, type (of text value
"<co>person</co>") and short-id respectively.

Element <co>contact</co> contains contact info of the
person.  <co>name</co> contains name data.
<co>contributions</co> -- the research profile data.
<co>affiliations</co> -- you guessed it.

The items which need mentioning are:

<dl>

<dt><co>contact/email-pub</co></dt>

<dd>Contains text "<co>true</co>" if user gave her
permission to publish her email address.  Contains
<co>&lt;undef/></co> otherwise.</dd>


<dt><co>name/additional-variations</co></dt>

<dd>the name variations, as set by the user on the name
screen</dd>


<dt><co>contributions/accepted</co></dt>

<dd>Research profile, list of identified works.</dd>


<dt><co>contributions/refused</co></dt>

<dd>Research profile, list of refused items.</dd>


<dt><co>about-owner</co></dt>

<dd>Contains text "<co>yes</co>" if the record describes the
account owner.  System adds this to every record normally
created by the registration process and uses it to build
appropriate elements of user interface ("your profile"
vs. "Vasya Pupkin's profile").</dd>

<dt><co>profile</co></dt>

<dd>External record presentation data.  <co>profile/url</co>
contains personal profile URL, <co>profile/file</co> -- the
profile filename path in the local filesystem,
<co>profile/export</co> -- names of files, to which the
record is exported.</dd>

</dl>





<h2 id='adm-slash'>Administrator's screens</h2>

Some administrator functions are available through the ACIS
web interface itself.  It makes monitoring and administering
the service easier.  Several <co>/adm/...</co> screens exist
for these functions.


<h3 id='adm-slash-access'>Access</h3>

Administrator screens are potentially a huge security risk.
Be sure that only trusted individuals have access to it.

There are two ways a user can get access to an administrator
screen.  First, she can enter a special password,
<c>admin-access-pass</c>.  If: 

- configuration defines this password and
- it is at least 6 characters long and
- one of the following:
  <ul><li>the user entered the same password or</li>
  <li>the password is present in the user's browser
  cookies,</li></ul>

then system lets her in.

When system asks the user for admin's password, there is an
option to save the password in a cookie.  Browser will store
the cookie for a month since its creation.  After that
browser will drop the cookie and you'll have to enter the
password again.

Second, a currently logged-in user might have an
administrator privilege.  A user has administrator privilege
if there is <co>admin</co> element in her userdata's owner
<co>type</co> element (XPath:
<co>/data/owner/type/admin</co>).  There is no way a user
can get administrator privilege other than by a manual edit
of her userdata file.

The second way to access the administrator screens is
preferable.  Especially, when you access it from a shared
computer, beause it doesn't leave the pass cookie.


### <C>/adm/sql</C>

This screen gives you capability to enter and execute any
SQL query on behalf of the ACIS' MySQL user and with
<c>acis-db-name</c> as the default database.

It prints out the query results, if any.


### <C>/adm/events</C>

The screen provides access to the <a
ref='events-database'>events database</a>, which contains a
log of everything what happened within ACIS' web interface.

The screen itself works in two modes: overview and data
retrieval.  Overview mode shows you for which years, months
and days there is data to browse and offers you access to
that data (i.e. hyperlinks).  The data retrieval mode shows
the actual events logged on a certain period of time.

There is also a subscreen for setting your preferences for
the data retrieval mode; see <a
ref='admeventspref'>below</a>.

Both modes of the screen are linked to each other and
provide navigational cues, which make it straightforward to
use; we hope so.



#### Checking a particular date

The overview mode offers a form (at the bottom of the
screen), which you can use to browse events for a particular
date or a period of time.  Just enter the starting date and
(optionally) the finishing date and click "SHOW" button.

Alternatively, you can directly request the screen to show
events for a particular date, via URL.  Add a date in format
YYYY-MM-DD to the URL of the <c>/adm/events</c>/ screen and
you get that.  E.g.,

    http://acis.super.edu/adm/events/2005-11-04

If you want to check events for a day starting from a
particular time, add "/HH:MM:SS" to an URL which has a date
already:

    http://acis.super.edu/adm/events/2005-11-04/12:03:45


#### Filters

There are several filters which you can enable via the <a
ref='admeventspref'>preferences</a> screen, or explicitly by
adding "?filter" or "?filter1+filter2" to the URL.

At this time there are two filters defined:

<dl>

<dt><co>hidemagic</co></dt>

<dd>Do not show so called "magic" sessions.  Magic sessions are those
created by ACIS machinery itself to do work on behalf of the users.
For instance, the <a href='apu.html'>APU</a> works via such sessions.
If you filter out the magic sessions, you will only the see the actual
users (supposedly, human) interacting with ACIS via the web
interface.</dd>

<dt><co>onlyresearch</co></dt>

<dd>A filter to show only events related to the research
profile.  Claiming or removing or refusing works will be
shown, everything else -- will not.
</dd>

</dl>

For example, 

    http://acis.super.edu/adm/events/2005-11-04?onlyresearch




#### <C>/adm/events/recent</C>

Shows the most recent events logged.  What is considered
recent depends on the preferences with a default of 12
hours.



#### <C>/adm/events/pref</C>

The screen to choose and set your preferences for working
with the <c>/adm/events</c> screens.  It requires cookies
and JavaScript in your browser.

The preference govern the maximum amount of data to load on
a page (it can be huge), filtering options, and an option on
presentation of the user sessions.  




### <C>/adm/search</C>

This screen gives you capability to search in some of the
important tables of ACIS.  It contains three search forms:
for documents, for records (personal records) and for
users.

You choose what field do you want to search by, enter the
search key and push [SEARCH].  If the key expression
includes "<co>%</co>" sign, it assumes that you use MySQL's
simple pattern matching syntax (operator <co>LIKE</co>).  In
that syntax <co>%</co> means zero or more of any character.
If your expression doesn't include percent character, it
assumes that you want full field value match.  For instance,
if you search by a known email address of a user and you
enter her complete address.

The search works differently when you search for documents
by title.  If you do not use percent char, it will search by
full-text index, so it will be a word search.  If you do use
the percent char, it will search by substring/phrase match.


Generally, this is a simple search utility.  It is not
supposed to provide complete information about the
documents, personal records and users in the system, just
the most basic info.


### <C>/adm/sessions</C>

This screen lists all currently open sessions, their type
and user name, and how old the session is.

You can look into each session (see all the data that is
stored in it) and delete it, if you think it has to be
deleted.


<!--

##  MySQL tables

ACIS creates and maintains several database tables for
itself.

-->



## Customizing an ACIS installation

An ideal web application is so flexible that you can build
it into an existing website seamlessly and you can customize
its wording and any other presentational aspects of it.
ACIS can not do that: it is too much to ask from us.

Instead, ACIS offers you two features to give you some
control over your site: phrases and semi-static pages.  
They support your need to communicate to your users
effectively.


<h3 id='phrases'>Phrases</h3>

Phrases are bits of (X)HTML markup which some of the ACIS
XSLT templates insert into the final pages in appropriate
context.  A phrase may be a single word or a whole bunch of
paragraphs; size doesn't matter.  Each phrase has its own
identifier and a default value; but you can override it.

For instance, the <co>service-intro</co> phrase is a slogan
that is displayed on ACIS homepage below the
<c>site-name-long</c>.  The default for this phrase is:

      <p><big>Through our service you tell the world 
      about yourself.</big></p>

and it is defined in the
<f>presentation/default/phrase.xml</f>.




<f>{HOME}/presentation/default/phrase.xml</f> is the default
phrases file.  You are welcome to take a look into this file
to see what phrases are there.  Sometimes, though, XSLT
stylesheet itself defines default content of a phrase.  That
happens when default content of a phrase needs to include
run-time specific values.  (Thus it cannot be written to a
ready-to-use <co>phrase.xml</co> file.)

If you want to override a phrase, you need to create
<f>{HOME}/presentation/default/phrase-local.xml</f> file:
 
      <phrasing>
      </phrasing>

and create <co>&lt;phrase id='...'> ... &lt;/phrase></co>
element inside it with id of the phrase you want to
override.  For example, <f>phrase-local.xml</f> may look
like this:

      <phrasing>

        <phrase id='service-intro'>
           <p><big>Register and be cool!</big></p>
        </phrase>

      </phrasing>

That will redefine the above-mentioned
<co>service-intro</co> phrase.

<!--
Any <co>phrase</co> entry that is not present in
<f>phrase-local.xml</f> will be taken from
<f>phrase.xml</f>.  If the phrase is not there, nothing will
be put into the resulting HTML; unless the default is
defined in XSLT itself.
-->

The other important phrases are:

<dl>

<dt><co>news</co></dt>

<dd>Service homepage includes <co>news</co> phrase right
after the <co>service-intro</co> phrase, before the
<strong>New registration</strong> section.</dd>

<dt><co>announcements</co></dt>

<dd>Returning users' welcome page shows this at the top of
the main content area (after the profile menu panel).</dd>

<dt><co>homepage-title</co></dt>

<dd>HTML page title of the service' homepage.
 Default: <c>site-name</c> + ": home", defined in
 <f>presentation/default/index.xsl</f>.</dd>


<dt><co>page-footer</co></dt>

<dd>Every page includes <co>page-footer</co> after the main
content <co>div</co>, inside <co>&lt;div class='footer'></co>.  By default it
includes: an administrator's email link, home link
(<c>home-url</c>) and a link to page top.

<p>The default is defined in <f>presentation/default/page.xsl</f>.</p>

</dd>

<dt><co>email-footer</co></dt>

<dt><co>email-footer-html</co></dt>

<dd>These footers are added to the email messages that
system generates and sends.  The difference is that the
first one is in plain-text and the other one is in HTML.
For consistency, define both equally if you re-define one of
them.  Default: empty.</dd>


<dt><co>new-registration-intro</co></dt>

<dd>The first screen of new registration includes this in
the main content <co>&lt;div></co>, right above the
"Introduce yourself" header.  Default: empty.</dd>


<dt><co>institution-search-instructions</co></dt>

<dd>Instructions for the institutions search form.  Default:
"<co>Enter main words of your institution name.  You may try
acronyms, too.</co>".</dd>


<dt><co>metadata-idenfitifer</co></dt> 

<dd>A word or a phrase to refer to identifiers in the
primary metadata.  The research profile's manual search
screen uses it.  For <a
href='http://authors.repec.org/'><abbr title='RePEc Author
Service'>RAS</abbr></a>, for instance, we use "RePEc
handles".  Default: "<co>metadata identifiers</co>".</dd>

<dt><co>research-main-epilog</co></dt>

<dd>The main research profile menu page displays it at page
bottom, after the menu table.  Default is in the
<f>phrases.xml</f>.</dd>

<dt><co>not-satisfied-with-automatic-search</co></dt>

<dd>This one will be shown under the heading "Not
satisfied with search results?" on the research profile
autosearch suggestion pages.  Default is in
<f>phrases.xml</f>.</dd>

<dt><co>email-confirmation-about-registering</co></dt>

<dd>A note about the registration, included into
confirmation email message text. Default: empty.</dd>

<dt><co>email-confirmation-no-works-claimed</co></dt>

<dd>Used in confirmation emails only if the user didn't add
any works to his research profile, while he registered.
Goes after the <co>email-confirmation-about-registering</co>
phrase.  Default: empty.</dd>


</dl>



Before ACIS displays a phrase content to the user, it
processes it in a specific way.  All simple XHTML it passes
through.  In addition to XHTML it might include some special
ACIS markup.  This special markup is not explained here;
actually it is not documented anywhere.  One interesting
case of special markup that you need to know is that you can
include other phrases in your phrase.  Example:

      <phrasing>
      
        <phrase id='news-brief'>
          <p><big>We celebrate a 100-years annivesary of the
          service!</big></p>
        </phrase>

        <phrase id='announcement'>
           <phrase ref='news'/>
        </phrase>

        <phrase id='news'>
           <h2>News</h2>

           <phrase ref='news-brief'/>
        </phrase>          

      </phrasing>



<h3 id='site'>Building a site around an ACIS installation</h3>

<p><strong><i>Semi-static pages of an ACIS site</i></strong></p>

Second customization thing you have is capability to create
web pages in ACIS.  System will serve these pages as if they
were a natural part of the service.  Thus you can publish
news, user instructions, FAQs on an ACIS site and develop
them over time.

When ACIS gets a request, it first checks the screens
configuration (<f>screens.xml</f> file).  If the request
does not match any of the screens in <f>screens.xml</f>,
ACIS checks <f>site/</f> directory of your ACIS home.  If
the directory contains an XML file with a matching pathname,
it will load this file and show it to the user.  A file has
a matching pathname if its relative pathname from
<f>site/</f> equals the requested address plus
"<co>.xml</co>".  For instance, if <c>base-url</c> is
"<co>http://web.site.org</co>" and request came for
"<co>http://web.site.org/about</co>", ACIS will check
<f>site/</f> directory for <f>about.xml</f> file.

The structure is simple: 

      <page>
         <title>page title</title>
         <content>
                
           <p>Once upon a time...  In a far, far end of the
           world...  There lived a page.</p>

         </content>
      </page>


<co>page</co> element may contain optional <co>name</co>
attribute and optional <co>style</co> elements.  The
<co>name</co> attribute for hiding links to a page on this
same page.  (Remind me later to expand on this.<!-- ZZZ -->)
The <co>style</co> elements are copied to the <co>head</co>
of the resulting HTML page.  Content of <co>content</co>
will go into the page body.

The pages will look as all other ACIS pages to the user.
They'll have the same standard header, the same footer, will
use the same styling.

In the header they'll have links appropriate to the user's
context.  If the user is undergoing an initial registration
process, the header will invite him to continue
registration.  To an already-registered user who logged-in,
the header will propose to return into account or log out.

When creating such pages, you'll want to check that the page
name won't conflict with any of the screens defined in ACIS.
Check <f>screens.xml</f> file for that.



<h2 id='installation-files'>Files in an ACIS installation</h2>


It will be useful if you know a little bit about what files
and directories does an ACIS installation consist of.  An
ACIS home directory will contain these items:

<table class='files'>

<tr><th>directory</th><th>what's in it</th></tr>

<tr>
<td class='f'>userdata/</td> 

<td>userdata files -- files, describing the users'
accounts</td>
</tr>

<tr>
 <td class='f'>sessions/</td>
 <td>files of currently open sessions</td>
</tr>

<tr>
 <td class='f'>lib/</td>
 <td>ACIS Perl libraries (source code)</td>
</tr>


<tr>
 <td class='f'>bin/</td>
 <td>ACIS utility scripts</td>
</tr>

<tr>
 <td class='f'>unconfirmed/</td>
 <td>finished, but not yet confirmed registration files</td>
</tr>

<tr>
 <td class='f'>deleted-userdata/</td>
 <td>the userdata files of users, who removed their accounts</td>
</tr>

<tr>
 <td class='f'>presentation/</td>

 <td>the XSLT templates, which generate HTML pages and
 emails; also some non-XSLT, but related files.</td> </tr>

<tr>
 <td class='f'>RI/</td>

 <td><a href='daemon.html'>Update daemon's</a>
 files: configuration, logs and data</td>

</tr>

<tr>
 <td class='f'>SID/</td>
 <td>short-id database logs and backups</td>
</tr>

<tr> <td class='f'>site/</td> <td>the semi-static page files,
 which ACIS will serve as native screens, see <a
 ref='site'>Building a site around an ACIS
 installation</a></td> </tr>


<!-- 
<tr>
 <td class='f'></td>
 <td></td>
</tr>
-->
</table>



<table class='files'>

<tr><th>filename</th>
 <th>description</th>
</tr>

<tr>
 <td class='f'>main.conf</td>
 <td>main configuration file</td>
</tr>

<tr>
 <td class='f'>ardb.conf</td>
 <td>ARDB configuration file, generated from <c>main.conf</c></td>
</tr>

<tr>
 <td class='f'>acis.conf</td>
 <td>ACIS::Web configuration file, generated from
<c>main.conf</c>
</td>
</tr>

<tr>
 <td class='f'>thisconf.sh</td>
 <td>shell script, containing all the configuration
parameters from <c>main.conf</c> as environment variables;
generated from <c>main.conf</c></td>
</tr>

<tr>
 <td class='f'>screens.xml</td>

 <td>ACIS::Web (Web::App) screens configuration.  See <a
 href='internal.html'>Internals Guide</a><!-- and possibly
 <co>perldoc lib/Web/App.pm</co> XXX -->.</td> 
</tr>

<tr>
 <td class='f'>configuration.xml</td>
 <td>ARDB data processing configuration. <!--  See <co>perldoc
lib/ARDB.pm</co>.  XXX --></td>
</tr>

<tr>
 <td class='f'>contributions.conf.xml</td>

 <td>Research contribution roles per research work type.
 (in <c>ACIS::Data::DumpXML</c> format).</td>

</tr>

<tr>
 <td class='f'>ri-socket</td>
 <td><a href='daemon.html'>Update daemon's</a> unix-domain
socket; the daemon listens to it.</td>
</tr>

<tr> <td class='f'>RI/collections</td> <td>RePEc::Index <a
 ref='ri-collections'>collections configuration</a>,
 generated from <c>main.conf</c></td> </tr>



<tr>
 <td class='f'>acis.log</td>
 <td>ACIS web-interface general log</td>
</tr>

<tr>
 <td class='f'>acis-err.log</td>
 <td>same as <co>acis.log</co>, but only troubles are logged</td>
</tr>

<tr>
 <td class='f'>sql.log</td>

 <td>MySQL queries log.  Normally, only client connections
 and failed queries are logged.</td>

</tr>

<tr>
 <td class='f'>ardb.log</td>
 <td>ARDB log</td>
</tr>

<tr> <td class='f'>SID/short-id.log</td> <td>Short-ids
 assignment log.  Very important file, never delete it and
 back up regularly.  It is important for short-id database
 recovery in case of trouble.  Short-id database consistency
 and continuity is essential to ACIS work and the metadata
 it produces.</td> </tr>


<tr> <td class='f'>RI/daemon.log</td> <td><a
 href='#ri-daemon'>Update daemon</a> log.  Includes all
 update requests, and shows which channel was each request
 given to for processing.</td>
 </tr>

<tr> <td class='f'>RI/update_ch0.log ...
 RI/update_ch5.log</td> <td><a href='#ri-daemon'>Update
 daemon</a> logs of processing the actual requests.  Each of
 the files correspond to one update daemon channel.  Show
 which datafiles and which records were found and show
 conflicts and other problems or findings about the data.
 Grow quickly.</td> </tr>


<tr> <td class='f'>RI/sql.log</td> <td>MySQL queries log for
 connections and queries done by the update daemon.</td> </tr>

<tr> <td class='f'>back.log</td> <td>ACIS background
 research searches log.  Each automatic research search is
 logged there with details on which particular name
 variations were searched and how many hits there were.</td>

</tr>


<tr> <td
 class='f'>presentation/default/phrases-local.xml</td>
 <td><a ref='phrases'>Phrases</a> local replacement
 file.</td>

</tr>

<tr> <td
 class='f'>presentation/default/phrases.xml</td>
 <td>Default <a ref='phrases'>phrases</a> file.</td>

</tr>

</table>





<id>$Id: adm.text,v 2.9 2007/04/24 15:37:35 ivan Exp $</id>
