ACIS project: phase 1 requirements
by Ivan Kurmanov and Thomas Krichel
Revision: 1.6 of Apr 11 2003. You should always be able to find the latest version of this document at: http://acis.openlib.org/documents/kathmandu.html.
Ed. Note: These are editorial notes.
Overall project goal:
The goal is to develop a tool for building interactive online CV services for academics. An existing prototype of such a service is HoPEc. The aim of our project is a more general, more flexible, more accessible and more functional system, based on a software that can be used with different metadata collections.
The requirements below tell about the system in the present tense as if it was already developed. This is just for the ease of reading.
We have organized this document as follows. First we list general (including main functional) requirements. Second, we list the requirements for the software from the point of view of the administrators of an ACIS-based service. Then we list the requiremnents of the funders of our work. Finally we have some notes on the requirements we impose on ourselves.
General functional and the service end-user's requirements:
- The system uses a collection of academic metadata as its database. Academic metadata includes data about research documents, research institutions, and researchers.
- The system gives researchers a friendly web interface to register themselves in a directory. The registration adds their personal data to the metadata collection.
- Registration in the service creates a metadata record with the person's name and contact details, affiliation information and references to documents. The references go to documents which this person authored or edited or otherwise contributed efforts to. The record may contain other relevant information that the person may want to publicize, e.g. research interests.
- A registration also creates an account in the service, which allows the registrant to log in back later to correct, update or delete her metadata record.
- The registrant's email address is used as the account login id. On initial registration the registrant chooses a password, that she uses to login back into the system.
When capturing email addresses, system defaults to a setting requiring that the email address not be made publicly available. By "not publicly available", we mean that it is not included into the metadata record of the person and it is not included in the data that the system has on public display.
The ACIS system administrators have access to the registrants' email addresses. We are confident that the system administrators will make use of the addresses that they have gathered in a way that is consistent with the practices of the communities that they serve.
When entering the email addresses on the system, the registrant may optionally request that the address be made publicly available.
All other registrant's data will be made publically available.
- The service tries to remember the registrant's email and (optionally) password, so that she doesn't have to re-enter this data the next time she wants to login to the system. (This functionality depends on HTTP cookies. But the cookies are not required to use the service. They are used if enabled, but the registrant can access all functions of the service without them.)
- When a registrant has forgotten her password, she can request an email message containing her password. If the registrant has forgotten under which email address she is registered, she will have to contact the system administrator.
- When a registrant changes her email address, an email notification of this change is mailed to both the old and the new address.
- The system accepts and stores user input in the UTF-8 encoding of Unicode. With modern browsers this means input can be in wide variety of languages.
Affiliation and employment profile
- One part of the personal profile that a registrant creates is her affiliation information. Affiliation covers both employment and membership of professional associations such as scholarly societies.
- The underlying metadata collection that ACIS is run upon is expected to contain data about the most important organizations that registrants may be affiliated with. This data is processed and included into the ACIS database.
- To specify an affiliation the registrant searches for it in the organizational database by name and then picks the correct ones from the results list.
In case a user didn't find her institution, an option is given
to submit some institution's data to the maintainer of the
corresponding metadata collection. While the corresponding
institution is not registered, the data that that the registrant
has supplied will be included in her metadata record.
Ed. Note: It is unclear how this "while" resolves and when. One possibility is that as soon as the person in charge for institutional data includes a supplied institution into his database, he would email the registrant. The registrant then would be expected to return to the service and replace the data she provided about the institution with a reference to a record in the institutions database.
Personal academic contributions profile
- A listing of related academic works is the key part of a researcher's CV. A database of academic works is the key part of the ACIS database. Academics use the service to claim their participation in creation of the works.
- The registrant's academic contributions profile consists of references to academic works which are part of the ACIS database. The system executes a search for the registrant's name in the academic works database and she is then able to choose appropriate ones from the list of works that are returned. The functionality of the contributionts page is the same as in the current HoPEc service, with the exception that the role of the registrant is added for all displayed works.
During the initial registration registrant enters her first, middle and
last names. The software then calculates a list of possible
combinations of the name components, as they may appear in
some document descriptions. For instance, if the first name is
"James", and the last name is "Bond", the list of possible
combinations should include at least:
- James Bond
- J. Bond
- Bond, James
- Bond, J.
- James Garcia Bond
- James G. Bond
- J. G. Bond
- Bond, James Garcia
- Bond, James G.
- Bond, J. G.
- Name searches are case-insensitive.
- The registrant's role in creation of each listed academic work can be specified, using a pull-down menu. The choice includes author and editor roles. The set of possible roles can be configured by the system administrator.
- After the initial registration and after each following update the service sends the registrant an email notification for a review of the changes. This is also a security measure.
- The system generates html files that provide a human-friendly view of the registrant's profile. An alphabethical directory listing of all registrants is provided.
Service administrator's requirements:
The Service administrator is the person who installs and runs the service software at a specific site on a specific metadata collection.
- The ACIS software is written in the Perl programming language. It requires the Mysql database software to run and some publically-available Perl modules.
- The software is well documented. It is easy to install and configure.
- The software configuration is governed by a textual configuration file.
- The system logs every significant event to its log file. In addition, it emails the administrator the new state of a registrant's profile each time it is created, deleted or modified.
- The service web interface part is a CGI program. It is developed for and tested with the Apache web server only.
- The service's web interface details are separated from the software source code. The interface is a set of template files, which define how the service looks to registrants and other users. A set of working templates is included in the ACIS package. The administrator can change the templates to alter the presentation of the service completely.
- W3C's powerful XSL Transformations (XSLT) technology will be used for templating the web interface look and feel.
- The way the software communicates to the registrant is conceptualized by as a screen model. It is documented in the ACIS screen model.
The system natively accepts metadata in the
AMF format. Files containing
the metadata are assumed to have the name ending '.xml'.
The design of ACIS allows extending the system to accept other data formats. The interface and requirements for that are described in the ACIS manual.
- In order to be treated by ACIS, an AMF record must have an id attribute. The value of the id attribute must be unique across the collection. Each <text> record must have a non-empty title property.
- Each metadata record created and managed by a registrant through the service is stored in a separate data file in a directory specified in the system's configuration. This directory can be made internet-accessible by the administrator (through an ftp or http server or both).
The output records are written in AMF format. The
AMF records have identifiers that belong to a
single namespace as fixed in the ACIS configuration.
The design of software allows extending the system to output other data formats. The ACIS manual describes how this can be done.
The funders' requirements (OSI):
- The software developed is released as open-source. We use existing open-source products throughout.
- The project documentation and progress reports are published on the web at http://acis.openlib.org.
The project team self-commitments:
- The software design is crafted carefully to allow easy debugging, corrections, later enhancements and third-party extensions.
- The software's internals are documented at least roughly.