## 1.1 Purpose
The purpose of this document is to present an overall description and listing of the functionality of a Publications Management System (PMS). This document is intended for the customers and suppliers of the system, including designers, testers, and the implementation unit.

## 1.2 Scope
The software product to be produced is the Publications Management System (PMS). The system will manage a database of bibliographical information and will be accessible via a command-line interface and a web browser.

The PMS will perform the following functions:
*   Store the full text of publications in PDF and PostScript formats.
*   Automatically retrieve bibliographical information, such as author and title, from the full text of a publication.
*   Provide the ability for users to manually correct any retrieved information that is incorrect or insufficient.
*   Explicitly manage author identities, allowing users to indicate that different name formats (e.g., ‘D. Vermeir’ and ‘Dirk Vermeir’) refer to the same person.
*   Support bulk updates for importing many publications at once.
*   Provide different levels of access to publication content, such as the full text or only the abstract, and support access control.

### 1.3.1 Product perspective
The Publications Management System (PMS) will rely on a database and a web server. The system can be accessed by a web browser and by a command line interface.

#### System interfaces
*   Database: The system contains an interface with a MySQL-Database.
*   Webserver: This server is responsible for the execution of the PMS, sending queries to the database, and generating the user interface.

#### User interfaces
Users can access the PMS from any operating system using a web browser that has a connection to the web server running the PMS. The PMS will be explicitly accessible for users with Linux as their OS and using a text-based web browser. The web interface will comply with the W3C XHTML 1.0 Transitional standard.

Administrators can access the system by command line from within the VUB network.

If an error occurs during a request, the user will receive an error message stating the cause of the error. The error will also be logged to notify administrators.

#### Hardware interfaces
There are no specific hardware requirements for the users.

#### Software interfaces
The PMS will run on a Linux-based environment, specifically the Wilma web server. It requires Ruby 1.8 or later to be installed. The use of frameworks is not allowed. Only free software can be used for tools and the end product.

#### Communications interfaces
Communication between the web server and users will be via an HTTP connection using TCP/IP port 80.

#### Memory constraints
There is no specific limit on the usage of memory by the PMS. However, publications will have a maximum file size, which is to be determined.

#### Operations
A user must be logged into the PMS or connected to the VUB network to use the system's functionality. Accessing the PMS from outside the VUB network is only possible for logged-in users. To log in, a user must first register for an account by providing their name, a password, and a valid e-mail address, followed by an e-mail validation step.

A backup and recovery structure for the database is required to save all data in case of server or disk problems.

#### Site adaptation requirements
The PMS will be easy to install on a Linux-based environment where Ruby 1.8 (or later) is installed.

#### Interfaces with services
[N/A]

### 1.3.2 Product functions
The software will provide a summary of the major functions available to different types of users. These functions are organized in a hierarchical user structure, where each subsequent user level inherits all functions of the preceding one.

The hierarchical user structure is as follows:
*   Guest
*   VUB-Network User
*   Member
*   Publisher
*   Moderator
*   Administrator

The major functions for each user level are:

*   **Guest**: A user who is not logged in and not on the VUB network.
    *   Register for an account.
    *   Log into an existing account.
    *   Validate a new account via email.
    *   Retrieve a forgotten password.

*   **VUB-Network User**: A user connected to the VUB network but not logged in.
    *   All Guest functions.
    *   Search for publications using basic and advanced criteria.
    *   Order, export, and download search results.
    *   Find publications with similarities to search results (e.g., same author, same institute).

*   **Member**: A registered and logged-in user.
    *   All VUB-Network User functions.
    *   Change personal account details (e.g., password, email).
    *   Log off from the system.

*   **Publisher**: A logged-in user with publishing rights.
    *   All Member functions.
    *   Upload single publications in PDF or PostScript format, following BibTeX or RIS standards.
    *   Perform bulk uploads of multiple publications.
    *   Edit their own uploaded publications.

*   **Moderator**: A logged-in user with moderation rights for their department.
    *   All Publisher functions.
    *   Manage user levels (upgrade/downgrade) for users within their department.
    *   Manage group permissions for groups under their jurisdiction.
    *   Edit author information.
    *   Edit any publication belonging to their department.

*   **Administrator**: A user with full system privileges.
    *   All Moderator functions.
    *   Access a control panel for system management.
    *   Create and delete any user account or group.
    *   Manage the user level of any user.
    *   Edit any publication in the system.

The following optional functions are considered for future expansion:
*   Support for additional document formats (e.g., MS WORD).
*   Displaying a list of documents that refer to a given publication.
*   Automatic recognition and merging of author and institute name variations (e.g., 'D. Vermeir' and 'Dirk Vermeir').
*   Automatic retrieval of full-text publications from URLs provided in BibTeX files.
*   Support for uploading and managing audio and video files.

### 1.3.3 User characteristics
The users of the PMS are expected to be academic personnel and students with various technical backgrounds. All users should have a basic knowledge of the internet.

Command line users are assumed to have access to the server shell and will have Administrator privileges, implying a higher level of technical expertise.

### 1.3.4 Limitations
The system must be developed using the Ruby programming language without the use of frameworks. Only free software can be used for the tools and the end product. The system must be able to run on a Linux-based environment, specifically the Wilma web server.

The design of the system must be modular and object-oriented. All design diagrams must follow the UML standard. The web interface must comply with the W3C XHTML 1.0 Transitional standard.

User accounts must be protected with personal passwords that are encrypted during submission and storage. Direct access to the database is only allowed for Administrators using the Command Line Interface. The system's availability is dependent on the availability of the Wilma web server.

## 1.4 Definitions
*   **Customer:** The person, or persons, who pay for the product and usually (but not necessarily) decide the requirements.
*   **Supplier:** The person, or persons, who produce a product for a customer.
*   **User:** The person, or persons, who operate or interact directly with the product.
*   **BibTEX:** A tool for formatting lists of references, typically used with the LATEX document preparation system.
*   **Bulk Update:** Importing many publications or abstracts at once (e.g., through BibTeX files).
*   **RIS:** A tagged file format for expressing bibliographic citations.
*   **Wilma:** A multifunctional linux server for the students of the faculty of sciences at the VUB.

# 2 References
*   IEEE Std 830-1998, IEEE Recommended Practice for Software Requirements Specifications. Published by the Institute of Electrical and Electronics Engineers (IEEE). Source: http://www.scribd.com/doc/2620639/IEEE-8301998
*   Software Engineering Course Project Description. Published by the Free University of Brussels (VUB). Source: http://tinf2.vub.ac.be/~dvermeir/courses/software_engineering/projects/2007-2008/index.html
*   XHTML 1.0 The Extensible HyperText Markup Language (Second Edition). Published by the World Wide Web Consortium (W3C). Source: http://www.w3.org/TR/xhtml1/
*   Git Distributed Revision Control System. Source: http://git.or.cz/
*   Institute of Electrical and Electronics Engineers (IEEE). Source: http://www.ieee.org/
*   RDoc - Document Generator for Ruby Source. Source: http://rdoc.sourceforge.net/
*   Software Engineering group 1 (SE1) Project Page. Published by the Free University of Brussels (VUB). Source: http://wilma.vub.ac.be/~se1_0708/
*   Free University of Brussels (VUB). Source: http://www.vub.ac.be
*   World Wide Web Consortium (W3C). Source: http://www.w3.org/
*   Coding Conventions of SE1. Published by Software Engineering group 1 (SE1), VUB. Source: http://wilma.vub.ac.be/~se1_0708/docs/coding_conventions/conventions.pdf
*   Unified Modelling Language (UML). Source: http://www.uml.org/
*   Software Quality Assurance Plan (SQAP) of SE1. Published by Software Engineering group 1 (SE1), VUB. Source: http://wilma.vub.ac.be/~se1_0708/docs/sqap/sqap.pdf
*   Software Test Plan (STD) of SE1. Source: To Be Determined.

## 3.1 Functions
If an error occurs during a request, the user will receive an error message stating the cause of the error. The error will be logged to notify the Administrator of technical difficulties.

### User Account Management
#### Register for an Account
A user can register for an account to become a Member.
1. The user selects the "Register" function.
2. The user provides a username, password, and personal data: name, login name, email address, university, and department.
3. The system checks if the username already exists.
4. The user confirms the registration.
5. The user must validate the new account via a validation email to complete the registration.

An exception occurs if the chosen username already exists. The result is that an email is sent to the Administrator, and a validation email is sent to the user.

#### Log In
A user can log in to the system.
*   **Preconditions**: The user must have a valid and confirmed account.
*   **Description**: Users outside the VUB-network are presented with a login screen. Users connected to the VUB-network are presented with a screen where they can either log in or start a search immediately.
*   **Exceptions**: The user is not registered or provides an incorrect username or password.
*   **Result**: The user is logged in and can access system functions according to their user level.

#### Log Off
A logged-in user can log off from the system.
*   **Preconditions**: The user is logged in.
*   **Description**: The user selects the "Logout" function.
*   **Result**: The user is logged off. If the user is on the VUB network, they are redirected to the search page. Otherwise, they are redirected to the login page.

#### Retrieve Password
A user who has forgotten their password can request a new one.
*   **Preconditions**: The user must have a registered account.
*   **Description**: The user selects the option to retrieve or change their password, provides their username, and enters a new password.
*   **Exceptions**: The provided username is not valid.
*   **Result**: An email is sent to the Administrator.

#### Change Account Details
A logged-in user can change their account information.
*   **Preconditions**: The user is logged in.
*   **Description**: The user selects the "Edit Settings" function, changes their personal data (e.g., password, email address, university, department), and confirms the changes. A user can also send a request to an Administrator for an account upgrade.
*   **Result**: The user's personal data is updated in the system.

### Publication Search and Retrieval
#### Search for Publications
A user can search for publications in the system.
*   **Preconditions**: The user must be logged in or connected to the VUB-network.
*   **Description**: The user fills in a search form with criteria:
    *   **Basic Search**: Keyword(s) with logical expressions (AND, OR, NOT), author(s), and a publication date range.
    *   **Advanced Search**: Additional keywords or publications that refer to the target publication.
*   **Result**: The system displays a list of publications matching the search criteria.

#### View and Manage Search Results
A user can view and manage the results of a search.
*   **Preconditions**: A publication search has been executed.
*   **Description**: The system displays the search results, showing the title and main author for each publication. The user can:
    *   Navigate through multiple pages of results.
    *   Order the results by title, author(s), and year of publication.
    *   View detailed information for a single publication or for multiple selected publications. Details include title, authors, publication date, abstract, and cited references.
    *   Search for publications by the same author(s), publications mentioned in a result, or publications by the same institute.
*   **Exceptions**: The search query returned no results.
*   **Result**: The user obtains a full, organized list of all results satisfying the search criteria.

#### Download Publications
A user can download the full text of publications.
*   **Preconditions**: A publication search has been executed.
*   **Description**: The user can download a single selected publication from the results screen or the detailed view screen. The user can also download all publications in a search result from the results screen.
*   **Result**: The user obtains an electronic copy of the selected publication(s).

#### Export Publication Data
A user can export the bibliographic data of publications.
*   **Preconditions**: A publication search has been executed.
*   **Description**: The user can export one or more of the obtained results to HTML, PDF, and PS formats. The user can also export the references cited in a publication to BibTeX (BIB) or RIS format.
*   **Result**: The user obtains a file containing the exported data in the selected format.

#### Consult References and Authors
A user can explore references and authors from the search results.
*   **Preconditions**: A publication search has been executed.
*   **Description**:
    *   The user can view the list of references cited in a single publication or in all publications from the search results.
    *   If a cited reference is also in the system, the user can navigate to its detailed view screen.
    *   The user can click on an author's name to view details about that author.
*   **Result**: The user can navigate through related publications and authors.

### Publication Management
#### Upload a Publication
A Publisher, Moderator, or Administrator can add a publication to the system.
*   **Preconditions**: The user is logged in with appropriate privileges. The document to be uploaded is in a supported format (PDF, PS) and follows the BibTeX or RIS format.
*   **Description**:
    1.  The user selects a document to upload.
    2.  The system automatically retrieves bibliographical information (author, title, etc.) from the document.
    3.  The system displays the retrieved information.
    4.  The user can accept the information or manually correct/complete it. The user can also specify that different name variations (e.g., 'D. Vermeir' and 'Dirk Vermeir') refer to the same author.
    5.  The user confirms the upload.
*   **Result**: A new publication is added to the system.

#### Bulk Upload Publications
A Publisher, Moderator, or Administrator can import many publications at once.
*   **Preconditions**: The user is logged in with appropriate privileges. The provided file (e.g., a BibTeX file) is in a supported format.
*   **Result**: Multiple new publications are added to the system.

#### Edit Publications
Users can edit publication information based on their privileges.
*   **Preconditions**: The user is logged in with appropriate privileges.
*   **Description**:
    *   **Publishers**: Can access a list of their own publications ("My Publications") and edit them.
    *   **Moderators**: Can edit any publication owned by their department or group. They can also edit author information.
    *   **Administrators**: Can edit any publication in the system.
*   **Result**: The changes to the publication are saved in the system.

### User and Group Administration
#### Search for Users
A Moderator or Administrator can search for users in the system.
*   **Preconditions**: The user is logged in as a Moderator or Administrator.
*   **Description**: The user selects the "Search Users" function and enters search criteria.
*   **Result**: The system displays a list of users matching the criteria.

#### Manage User Accounts
Users with sufficient privileges can manage other user accounts.
*   **Preconditions**: The user is logged in with appropriate privileges.
*   **Description**:
    *   **Moderators**: Can upgrade a Member from their own department to a Publisher, or downgrade a Publisher to a Member. They can also edit the settings of users.
    *   **Administrators**: Can create new user accounts, delete any user account, and change the user level of any user to any other level.
*   **Exceptions**: When creating a user, the username already exists. When deleting a user, the username does not exist.
*   **Result**: User accounts are created, deleted, or modified.

#### Manage Groups
Users with sufficient privileges can manage groups.
*   **Preconditions**: The user is logged in with appropriate privileges. To delete a group, it must be empty.
*   **Description**:
    *   **Moderators**: Can change the permissions of any group under their jurisdiction.
    *   **Administrators**: Can create, search for, edit, and delete any group.
*   **Exceptions**: When creating a group, the group name already exists. When deleting a group, the group name does not exist or the group is not empty.
*   **Result**: Groups are created, deleted, or modified.

### System Administration
#### Access Control Panel
An Administrator can access a control panel to manage the system.
*   **Preconditions**: The user is logged in as an Administrator.
*   **Description**: The control panel provides access to system-wide management tasks, such as managing user accounts and system settings.
*   **Result**: The Administrator can perform system-wide management tasks.

#### Edit System Configuration
An Administrator can change system configuration settings.
*   **Preconditions**: The user is logged in as an Administrator.
*   **Description**: The Administrator accesses the configuration panel and changes system settings.
*   **Result**: Configuration changes are applied to the system.

## 3.2 Performance requirements
[N/A]

## 3.3 Usability requirements
*   The web interface shall be attractive and simple.
*   The clarity and structure of the web interface are very important.
*   The web interface shall be designed to be fast and efficient, allowing users to fulfill all available tasks in the minimum number of pages and clicks.
*   The system shall be accessible to users with a text-based web browser on a Linux operating system.
*   If an error occurs during a user request, the system shall display an error message stating the cause of the error.
*   During system downtime, the system shall display a message to visitors stating that it is temporarily unavailable.

## 3.5 Logical database requirements
All static and dynamic information will be saved in the database, including statistics, publications, and administrator settings.

The types of information stored include:
*   Publication data, including bibliographical information and the full text of publications in PDF and PostScript formats.
*   User account information, including personal data, user level, and encrypted passwords.
*   Group information.

The database must be capable of handling several concurrent requests via SQL statements. Direct access to the data stored in the database is restricted to Administrators using the Command Line Interface.

The database must be kept consistent at all times, with no pointers to deleted records and no redundant information.

For security, user passwords must be stored in an encrypted format.

A backup structure is required to save all data in case of server or disk problems.

Frequency of use: [N/A]

Data entities and their relationships: [N/A]

Data retention requirements: [N/A]

## 3.6 Design constraints
*   The design of the PMS shall be modular to simplify the design and implementation of expansions and replacements.
*   The implementation must be object-oriented.
*   The implementation must be compliant with the Coding Conventions of SE1.
*   The used programming language will be Ruby.
*   The use of frameworks is not allowed.
*   Only free software can be used for the tools and for the end product.
*   The PMS must be able to run on Linux, specifically the Wilma web server.
*   The PMS web interface must conform to the W3C XHTML 1.0 Transitional standard.
*   Design diagrams must be made following the UML standard.
*   The code will be documented using RDoc.
*   Git will be used for configuration management.

## 3.7 Software system attributes
### Reliability
The system shall be developed to minimize software faults through a spiral development model with two iterations.

### Availability
The system will be available at all times, except when the Wilma server is unavailable. In case of a corrupted database, an Administrator shall be able to replace the database with the last available backup. In case of another failure, the problem should be solved and the system reinitialized. During downtime, the system shall display an error message to visitors stating that it is temporarily down.

### Security
*   Every user account must be protected with a personal password.
*   User passwords must be encrypted when submitted from the user to the server and must be stored in an encrypted format in the database.
*   Direct access to the data stored in the database is only allowed for Administrators using the Command Line Interface (CLI).
*   The defined user levels must be respected with regard to editing, deleting, and uploading publications.

### Maintainability
*   The design of the system shall be modular to simplify the design and implementation of expansions and replacements.
*   The code will be documented using RDoc.

### Portability
The system is developed and tested to run on the Wilma server, a Linux-based platform. Relocating the system to a server with a different operating system is possible as long as all necessary software, such as Ruby, is available.

## 3.8 Supporting information

### Apportioning of Requirements
To provide an early prototype, requirements are apportioned into multiple iterations. Functions are prioritized as follows:
*   Critical (C): Needed for the first iteration.
*   Sufficient (S): Needed for the second iteration to have an adequate end product.
*   Optional (O): To be implemented if time permits.

### Supported Data Formats
*   Input formats for publications: PDF, PS, ODT.
*   Input formats for bibliographical data: BibTeX, RIS.
*   Export formats for search results: HTML, PDF, PS.
*   Export formats for references: BibTeX, RIS.

### Installation
The system will be easy to install and will run in a Linux-based environment with Ruby 1.8 or later installed. It must be able to run on the Wilma web server.

## 4.1 Functions
[N/A]

## 4.2 Performance requirements
[N/A]

## 4.3 Usability requirements
[N/A]

## 4.5 Logical database requirements
[N/A]

## 4.6 Design constraints
[N/A]

## 4.7 Software system attributes
### Reliability
Reliability will be verified by executing the test cases and processes defined in the Software Quality Assurance Plan (SQAP) and the Software Test Plan (STD). This will ensure the system is not prone to software faults.

### Availability
Availability will be verified by testing the specified recovery procedures:
*   Simulating a database corruption and verifying that an Administrator can successfully restore the database from the last available backup.
*   Simulating a system failure and verifying that the system can be reinitialized.
*   Verifying that during a simulated downtime, the system provides an error message to visitors stating that it is temporarily down.

### Security
Security attributes will be verified through the following tests:
*   **Authentication**: It will be verified that user accounts are protected by a password and cannot be accessed without the correct credentials.
*   **Encryption**: It will be verified that passwords are encrypted during submission from the user to the server and are stored in an encrypted format in the database.
*   **Access Control**:
    *   It will be verified that direct access to the database is only possible for Administrators using the Command Line Interface (CLI).
    *   Tests will be conducted for each user level to ensure that permissions for editing, deleting, and uploading publications are correctly enforced.

### Maintainability
Maintainability will be verified through code and design reviews to ensure the implementation is modular, as required.

### Portability
As the system is developed for a specific platform and portability was not a primary requirement, no formal verification tests for portability will be performed.

## 5.1 Assumptions and dependencies
*   The users must have a web browser that supports W3C XHTML and have a TCP/IP connection to the web server.
*   The HTTP traffic must be possible on the network connection between server and client.
*   Command line users have access to the server shell and therefore have all Administrator privileges.
*   The PMS will run on a Linux-based environment, specifically the Wilma web server.
*   The availability of the PMS is dependent on the availability of the Wilma web server, which is an issue that should be handled by the customer.

## 5.2 Acronyms and abbreviations
*   BibTEX: A tool for formatting lists of references, typically used with the LATEX document preparation system.
*   Bulk Update: Importing many publications or abstracts at once (e.g., through BibTeX files).
*   CLI: Command Line Interface.
*   Git: A distributed revision control / software configuration management project.
*   HTML: Hypertext Markup Language.
*   HTTP: Hypertext Transfer Protocol.
*   IEEE: Institute of Electrical and Electronics Engineers.
*   OS: Operating System (e.g., Linux, MS Windows XP, Mac OS X).
*   PDF: Portable Document Format.
*   PMS: Publication Management System.
*   PS: Postscript.
*   RDoc: Document Generator for Ruby Source.
*   RIS: A tagged file format for expressing bibliographic citations.
*   Ruby: A reflective, dynamic, object-oriented programming language.
*   SCMP: Software Configuration Management Plan.
*   SE1: Software Engineering group 1.
*   SQAP: Software Quality Assurance Plan.
*   SRS: Software Requirements Specification.
*   STD: Software Test Plan.
*   TBD: To Be Determined.
*   UML: Unified Modelling Language.
*   VUB: Free University of Brussels.
*   W3C: World Wide Web Consortium.
*   Wilma: A multifunctional linux server for the students of the faculty of sciences at the VUB.