Library Requirements

I. Introduction

The following is a requirements document for the Library System for OpenACS 3.2.4. The Library System is somewhat narrower in scope than general application packages; this document should reflect that in its vision statement and general brevity.

II. Vision Statement

Most people own a couple books. If such people want to expand their literary explorations without spending much, borrowing from friends, particularly people with similar taste, is an excellent way to find more material. The Library System was conceived of to allow readers an online method of keeping track of their own collection and borrowing from other users.

An important aspect of the Library System is its increased benefit for users geographically close to one another. While borrowing books long-distance is not unheard of, it is somewhat impractial for the average person to ship and reship books. Thus communities using the Library System are more likely to be physical communities as well as virtual ones, such as collegiate campuses.

III. System Overview

The Library System consists of:

• Web-based tools for book information management:

  • Obtaining book information (title, author, publisher, publication year, edition, and page length) from other sites

  • Associating user-specifc information with any books they own

  • Methods for merging duplicated information

  • Simple administrative and user interface for modifying and correcting information

• Web-based tools for book borrowing:

  • Locate owners of a certain book, either to borrow it or to see what else they own

  • See if any book is currently not being borrowed and request it through interface

  • Manage loaning and returning through email-based exchanges

  • Queue requests for books currently being borrowed

The borrowing and merging subsystems may be generalized to facilitate other media such as CDs and magazines.

IV. Use-cases and User-scenarios

The Library System is intended for the following classes of users, which may or may not overlap:

• Site-wide administrators (referred to as 'the administrator') decide whether or not to use the Library System and manage its configurations

• Content administrators (referred to as 'the content admin') are designated by the administrator and manage user-provided content

• Registered users (referred to as 'the user') input book information and borrow books from one another

Initial System Installation

Andrew Admin decides his friends at college could use the Library System after a recent book-buying frenzy. After obtaining and unzipping the system, he runs the SQL script by Postgres and places files in their relevant folders. Upon restarting the server, the Library System is freshly installed and ready for use. Andrew Admin then configures the library system to use

Content Population

Joe and Jane User, registered on Andrew Admin's OpenACS site, are avid readers and begin to populate the Library System with entries from their own collection.

Content Management

Maddie Manager, designated by Andrew Admin to manage user-contributed content,

V. Related Links

• Library Documentation

VI.A Requirements: Data Model

• 4.500.0 Package Identification
  (All of these items are entered by the developer using the developer UI.)

  4.500.1 A human readable package key that is guaranteed to be unique to the local ACS site must be maintained by the APM. For example, "apm."

  4.500.5 A package id (primary key) that is guaranteed to be unique to the local site must be maintained by the APM. For example, "25."

  4.500.10 A package URL that is guaranteed to be unique across all sites must be maintained by the APM. The package URL should point to a server that allows download of the latest version of the package. For example, "http://software.arsdigita.com/packages/apm.apm."

• 4.505.0 Version Identification
  (All of these items are entered by the developer using the developer UI.)

  4.505.1 A version id (primary key) that is guaranteed to be unique to the local site must be maintained by the APM.

  4.505.5 A version URL that is guaranteed to be unique across all sites must be maintained by the APM. The version URL should point to a server that allows download of a specific version of the package.

VI.B Requirements: API

The API for APM v3 is explicitly a private API. However, it would be useful to obtain information from the APM through a procedural API. Implementing the API specified below is quite easy given that there are pages that already do all of the below in raw SQL.

• 4.400.0 Packages Status Predicates

  4.400.1 Given defining information such as a package URL, the APM API can return the status of the package on the local ACS instance.

• 4.405.0 Package Information Procedures

  4.405.1 The APM API can return information for any locally installed packages, including the version number, paths and files, and package key.

• 4.410.0 Sub-site Procedures

  4.410.1 After a package has been installed at the site-wide level, the system API will provide means to check for package presence, creation, enabling, disabling, and destruction on a subsite.

• 4.415.0 Parameter Values (replaces ad_parameter)

  4.415.1 The system API shall allow subsite parameters for an installed package to be set by either site-wide administrators or sub-site admins. The subsite parameter can be set to be non-persistent (but default is to survive server restarts). The subsite parameter can also be set to only take effect after a server restart (default is immediate).

  4.415.5 Parameters for a given subsite and package can be returned by the system API.

VI.C Requirements: Security

Provisions will be made to assure that packages are securely identified.

• 4.600.1 Each package will have a PGP signature and there will be MD5 time stamps for each file within the package.

• 4.600.5 The APM will provide a facility to validate both the PGP signature and MD5 stamps information before a package install.

VI.D Requirements: The User Interface

The user interface is a set of HTML pages that are used to drive the underlying API. It is restricted to site-wide administrators because the actions taken here can dramatically affect the state of the running ACS.

VI.E Requirements: The Developer's Interface

The intent of the developer's interface is to enable the developer to construct and maintain APM packages. It will be possible to disable the developer's interface for production sites to help reduce the chance of site failure; much of the functionality here can have cascading effects throughout the ACS and should not be used on a production site.

• 10.0 Define a package.

  The developer must be able to create a new package by specifying some identifying information for the package. This includes a package name, a package key, version information, owner information, and a canonical URL.

  10.1 The APM must maintain the state of all locally generated packages.

  10.50 If the developer fails to provide the required information, the package cannot be created.

  10.55 All of the package information should be editable after creation, except for the package key.

  4.10.60 The package creator must specify whether the package is capable of being used in sub-sites, or if only a single, global instance of the package is permitted.

  4.10.65 If the developer fails to provide unique information for unique fields specified in the data model requirements, the package cannot be created.

• 20.0 Add files to a package

  20.1 The developer must be able to add files to the package. This is done by copying the files into the package directory in the host OS's file system. Files can be added at any point after package creation.

  20.3 Once a package has been versioned and distributed, no new files should be added to the package without incrementing the version number.

  20.5 The APM's UI should facilitate the process of adding new files, by scanning the file system for new files automatically, and allowing the developer to confirm adding them.

  20.10 The developer cannot add files to a given package via the UI that do not exist in the file system already.

  20.15 Package file structure must follow a specified convention. Please see the design document for what we do currently.

• 30.0 Remove files from a package

  The developer must be able to remove files from a package. This can be done in two ways.

  • 30.1 Access the APM UI, browse the file list, and remove files.

    30.1.1If a file is removed from the package list, but not from the file system, an error should be generated at package load time.

  • 30.5 Remove the file from file system.

    30.5.1 The APM UI should take note of the fact that the file is gone and offer the developer an option to confirm the file's deletion.

• 40.0 Modify files in a package.

  40.1 The developer should be able to modify files in the file system. The APM UI should not interfere with this.

  40.5 However, if the developer modifies files containing procedural definitions, APM UI should allow a means to watch those files and automatically reload them if changed. See requirement 50.0 for more detail.

  40.10 Also, although a change in files implies that the package distribution file is out of date, it is the developer's responsibility to update it.

• 4.45.0 Manage Package Dependency Information.

  4.45.1 The developer should be able to specify which interfaces the package requires.

  4.45.5 The developer should be able to specify which interfaces the package provides.

  4.45.10 Circular dependencies are not allowed.

• 50.0 Watch a file

  4.50.1 The developer should be able to assign a watch to any Tcl procedure file, whether in /packages or /tcl.

  50.5 If a watched file is locally modified, then it will be automatically reloaded, thus allowing for any changes made to take affect immediately.

  4.50.10 The setting of a watch should be persistent across server restarts.

• 60.0 Display an XML package specification

  60.1 The developer should be able to view the XML package specification that encodes all package information.

• 70.0 Write an XML package specification to the file system

  70.1 The developer should be able to write an up-to-date XML specification to disk.

  70.5 The developer should be able to request the current XML specification for all installed, locally generated packages.

• 130.0 Distribution file generation

  130.1 The developer should be able to generate a .APM distribution file for the package with just one click.

  130.5 Generating a distribution file implies doing an "up-to-date" check on all of the files. If any of the files have changed since package installation, then a new version of the package is created.

• 140.0 Access CVS information

  140.1 The developer should be able to determine the CVS status of a package, or all packages, with a single click.

• 4.200.0 Compound Package Construction

  4.200.1 The developer can include .APM packages (sub-packages) within a package (the compound package) like any other file.

  4.200.5 The recommended usage for this feature is to allow for separation of optional and required components from the installation as well as better organization of files once installed. For example, all documentation for the community-core can be packages as community-core-doc.apm. It is legal to include sub-packages with dependencies that are not satisfied by the packages in the compound package, but this is discouraged. In such a case, the sub-package should really be a separate package that is required by the compound package.

  4.200.10 If a sub-package is required for the installation of the compound package, the compound package should have a registered dependency on the sub-package.

VI.F Requirements: The Site-Wide Administrator's Interface

The requirement of the administrator's interface is to enable the administrator to install, enable, upgrade, disable, deinstall, and delete packages.

• 80.0 Package Enable/Disable

  4.80.1 The administrator should be able mark an installed package as enabled. This means that the package is activated and its functionality is delivered through the Request Processor. As of ACS 4, this is done through the sub-site system.

  4.80.5 Moreover, the administrator must be able to disable a package, thereby removing the functionality provided to a sub-site. As of ACS 4, this is done through the sub-site system.

• 90.0 Package Install

  90.1 The administrator must be able to install new packages either from locally maintained .APM files or from URLs.

  90.5 In the case of an URL, the APM transparently downloads the APM file off the web, proceeds with a file based installation, and then optionally removes the .APM file just downloaded.

  90.10.1 If .APM files are present in a package, then it is considered a compound package (use 4.210.0).

  90.15.0 Installation requires these steps:

  1. 90.15.1The package dependencies are scanned. If some dependencies are not present, the system warns the administrator that installation cannot proceed until those packages are installed.
  2. 90.15.2 Assuming all dependencies are present, APM extracts the contents of the APM file into the /packages directory.
  3. 90.15.3 The administrator is offered the option of importing directly into CVS.
  4. 90.15.4 The administrator is given a list of data model scripts found in the package and can select which ones to be executed.
  5. 90.15.5 If no errors are recorded during this process, the package is enabled.

• 4.210.0 Compound package Install

  4.210.1 If .APM files are present in a package, then it is considered a compound package.

  4.210.5.0 Installation of a compound package proceeds according to the following sequence:

  1. 4.210.5.1 Identify the set of all sub-packages within the compound package by scanning for all files with .APM.
  2. 4.210.5.2 Identify which sub-packages are required by checking the dependencies of the compound package. If there dependencies not satisfied by the current system or the packages included with the compound package, halt installation and inform user to install these packages first.
  3. 4.210.5.3 Present Administrator with the ability to choose which sub-packages to install. Required sub-packages must be installed.
  4. 4.210.5.4 Proceed with the installation of each sub-package, starting with required packages. If the sub-package is already installed, then do nothing. Else, If the sub-package is a normal package, proceed according to 90.15.0, otherwise if it is a compound package, proceed according to 4.210.5.0.
  5. 4.210.5.5 If all required sub-packages are installed, proceed to install non-required sub-packages. If there was a failure during the installation of a required sub-package, then the installation of the compound package is also a failure.
  6. 4.210.5.6 Any attempt to install a compound package in the future involves a choice presented to the admin of installing any uninstalled sub-packages.

• 4.220.0 Recovering from failed package installation

  4.220.1 If any error is generated during package installation, the package is not considered installed. To recover from this failure, the package should be selected for installation again.

• 100.0 Version Upgrade

  100.1 The administrator can upgrade to a new version of a package. This entails

  1. 100.1.1 Running any necessary and included upgrade scripts.
  2. 100.1.5 Replacing any old files with new versions.
  3. 100.1.10 Marking the old version of the package as 'superseded' and disabling it.
  4. 100.1.15 Assuming no errors from above, the new package is enabled.

• 110.0 Package Deinstall

  110.1 The administrator must be able to deinstall a package that has already been installed. Deinstallation entails:

  1. 110.1.1 Running any data model scripts necessary to drop the package.
  2. 110.1.5 Moving all of the files into a separate location in the file system from the installed packages.
  3. 4.110.1.10 If the package is a compound package, then the administrator must confirm removing all sub-packages. Optionally, some sub-packages can be kept.

  110.5 Deinstalled packages can be re-installed at a later date.

  4.110.10 If deinstalling a package or any of its sub-packages breaks a dependency, then deinstallation cannot proceed until the package registering the dependency is removed.

• 120.0 Package Deletion

  120.1 The administrator should be able to completely erase all records of the package. This involves removing all instances of the package, all related database tables and content.

  120.5 This option can only be used if all package instances are deleted or marked as disabled. This is purposefully cumbersome because deleting all instances of a package can have far-sweeping consequences throughout a site and should almost never be done.

• 150.0 Scan for new or modified packages

  150.1 The administrator should be able to scan the file system for any changes made in any of the installed package files.

  150.5 The administrator should be able to scan the file system for any newly installed packages.

VI.G Requirements: The Sub-Site Administrator's Interface

If the developer is in charge of creating packages and the administrator for installing them, then the sub-site administrator is responsible for configuring and enabling packages. In order for a package to be available for a sub-site it must be associated with the sub-site's type specification. This interface is part of the sub-site /admin interface.

• 4.300 Creating a package instance.

  4.300.1 From the sub-site /admin interface, there should be an option to view all packages available in the system as well as an option to add a package to the subsite.

  4.300.5 From the "add" option, the sub-admin can select from a list of packages registered as available in the sub-site type to which the sub-site belongs.

  4.300.19 Once a package instance is added, it is available on the list of the subsite's available packages.

• 4.305 Configuring a package instance.

  4.305.1 An automatic web interface that lists all parameters with current values must be available.

  4.305.5 Changing the values for the parameters is accomplished simply by submitting an HTML form.

• 4.310 Enabling a package instance.

  4.310.1 The sub-admin should be able to enable a package with a single click. Enabling a package means that the ACS will serve its URLs properly.

• 4.315 Disabling a package instance.

  4.315.1 The sub-admin should be able to disable a package with a single click. Disabling a package means that the ACS will no longer serve those URLs.

• 4.320 Deleting a package instance.

  4.320.1 Deleting a package instance involves deleting not only the package instance, but any and all content associated with it. It is questionable whether this option should even be available due to its drastic consequences. Reviewer comments appreciated.

VII. Revision History

Document Revision #	Action Taken, Notes	When?	By Whom?
0.1	Creation	01/10/2001	Ryan Lee