Forum OpenACS Development: Re: OpenACS Attribute Management - Requirements/Requests

ACS Attribute Management System Requirements

Document written by Matthew Geddert and Richard Hamilton

I. Introduction

This is a requirements document for the OpenACS Attribute Management System (AMS). AMS provides an abstraction layer between the content repository, the templating system and client modules such that a developer can create and implement user extensible data structures.

II. Vision Statement

To make websites as easy as possible to learn to use, a consistent ‘look and feel’ of the user interface is important. For site publishers and administrators, separating aspects of the UI from the underlying program logic makes for easier maintenance and more efficient workflow. The OpenACS supports this by providing the ACS Templating system which separates elements of program logic from those of design. An important part of the ACS Templating service is the ‘ad_form’ procedure. This procedure provides a convenient declarative syntax for rendering data driven html ‘forms’ for information display and edit pages in web browsers, taking care of all ancillary aspects of form driven functionality including widget allocation, data validation and submission.

Similarly, to efficiently support central services such as security and revision management, and to provide abstraction from the RDBMS in the form of a content delivering API, the OpenACS stores information in a central repository known as the ACS Content Repository (CR). Developers are encouraged to use the content repository for new modules rather than implement their own application specific data models (which would then fall outside the capabilities of the general OpenACS content management applications).

The OpenACS CR data model is designed to be extremely flexible and supports the modelling of hierarchically organised entities (referred to as content items or objects) to which attributes can be attached in a manner analogous to attributes in a single table in an RDBMS. CR content objects can further be grouped into folders whereby all objects in the folder become descendents of the folder object (which is itself a special type of content object). To provide almost unrestricted flexibility, CR content items can also be related to each other in arbitrary ways through the acs_rels data structure.

This flexible data model provides for the possibility of creating applications that allow site users to exert direct control over attributes stored in the CR so that applications can be customised in extremely flexible ways without additional program logic being required. In order to realise this goal functionality is required that can create user pages for displaying and modifying data structures programmatically. To achieve this a means of storing information about dynamically created data structures must be designed such that calls to ad_form can be generated automatically following an AMS API call according to the structure of any specified data.

The AMS will provide:

- Mechanisms that allow application developers to more easily exploit the power, convenience and flexibility of the content repository without needing to have any understanding of its structure or API.
- Abstraction from the details of ad_form specifications.
- Abstraction from the db/CR layers for module level data retrieval.
- Mechanisms that allow authorised users to customise data structures and definitions in OpenACS applications.
A system for maintaining an audit trail at various levels of atomicity entirely at the control of the user upon data definition.

III. System Overview

The AMS will comprise:

·        A data model that conforms to and/or integrates fully with and enhances the existing CR data model whilst eliminating the need for separate CR tables for each CR object type managed by AMS. (This will be possible since AMS calls will be the standard way to access AMS managed content objects).

·        A library of tcl API calls which

a.      support and simplify the use of the CR in application development.

b.      return appropriate datasets from the content repository for display.

c.      return appropriate ad_form input specifications for data manipulation.

d.      expose attribute management functionality to the developer for inclusion in new modules.

e.      provide developer access to the underlying AMS pl/pgsql functions.

f.        provide an admin user interface that developers can include in their modules where users can manage attributes related thereto.

IV. Use-cases and User-scenarios

At present it is typical that application logic expects data in non-flexible form and requires query output in a predetermined form. Accordingly the SQL that provides data to tcl pages itself depends upon the fixed underlying data model. Inclusion in applications of additions to that data model require changes to both SQL and tcl code layers.

The AMS will be designed as an OpenACS service that provides attribute management services to modules for programmers to incorporate in their applications. As noted in the requirement for ACS Templating programmers are generally responsible for defining and implementing the application logic of a site. Just as ACS Templating separates presentation from application logic, so AMS will separate data definition from application logic.

AMS must provide mechanisms that support these requirements and allow the programmer to create ‘empty vessel’ applications that the user can customise for their own specific purposes.

Pages delivered by ACS Templating are split into two component parts. The presentation component is concerned with how to display the page, the underlying logic component contains the application logic that provides the page output data. It is in this logic component that calls to AMS will be used, in place of custom queries and data handling.

What is needed is:

- A notation and API for the programmer to generate the data to be displayed. In OpenACS, we call the data that we wish to display a ‘data source’ or ‘page property’.
Application logic is driven by the inputs the page gathers from the user request (e.g. the HTTP request), and the computation that the page must perform on this input. This computation will generally create and populate the data sources and page properties. Where in the past data sources tended to be connected to database queries, now (at least for user customisable attributes) they will be connected to an AMS API call.
- A mechanism for the developer to influence the specification that AMS provides to ad_form for the rendering of forms from customised data structures.
- A mechanism and API for the programmer to use when creating admin pages in his application that support user defined data structures.
- A notation and API for defining attributes and records where a record will be an OpenACS CR ‘record’ object that has child objects that are attributes (in this way AMS can support user defined complex compound data types analogous to the current OpenACS standard for ‘typed’ data in the CR).

Use-Case 1

Danny Dreamer wants to write a ‘contacts’ package where users can specify data structures according to their needs. He instantiates his new package and writes some admin pages that call the AMS API so that he can define a test data structure. He now constructs his user pages just as usual but using calls to AMS rather than to the database API or the CR direct. Because he wants to simply ‘attach’ arbitrary data to acs parties in his application Danny does not define an AMS record.

By doing this all of the detail of defining acs objects and creating CR object tables is abstracted from Danny in the writing of his application. In addition, because AMS is fully integrated with the CR, he will receive all the benefits in his application of his users’ customised data being part of the CR object system (i.e. permissions etc.) and a flexible and customisable logging and revision management scheme (at field level) which is at his users’ control. Also, because attributes associated with each package instance are children of a package ‘root’ folder, his new contacts package will be instance aware and permissions will be available by site node and ACS party.

Use-Case 2

Olly Optimist decides to write a new Edit-This-Page module for the OpenACS one weekend (he has to complete it by Monday because he is moving house and won’t have time to finish it after that!). He wants to have an admin interface that allows users to create custom page types and custom applications just as ETP now does. Unlike Danny he does not want a log of every change to every field, he simply wants to keep revisions of changes to a page (i.e. an AMS record).

He instantiates the original ETP application (minus the CR init scripts) as the basis for his new package and writes some admin pages that call the AMS API so that he can define a test application and a test record structure. He now finds that using AMS he can write the new ETP quite quickly, particularly given that the bulk of his admin pages are provided for him by AMS.

His application is finished quickly and works well because the difficult parts are already taken care of by the AMS service which is (by now hopefully) fully de-bugged. He shares all the benefits with Danny of the CR however unlike Danny’s application, Olly’s new ETP logs revisions at the ‘record’ (page) level.

Some months down the line Olly finds that one of his friends has thought of an application for the ETP package that requires him to log ALL changes at the field level. Olly looks anxiously at the API docs for AMS and discovers to his relief that this is easy to accomplish. All he has to do is define attributes as NOT children of an AMS record and make the appropriate logging selections using the AMS API data definition admin pages which he used to build his ETP application admin pages.

Olly’s friend is very impressed!

V. Related Links

·        Design document (to be written)

VI.A Functional Requirements

·        10.0 A Common Solution

Programmers and users should only have to learn a single system that serves as a substrate for all the functionally specific modules in the toolkit.

10.0.1

The system should not make any assumptions about how pages should look or function. AMS usage should have no functional impact on design issues other than in so far as modules such as list builder and ad_form influence the creation of a standardised and consistent user interface across modules. This positive influence should be supported by AMS.

10.0.3

Users should be able to recognise the attribute customisation admin pages irrespective of the module that they are customising. Once a user has learned how to use the AMS attribute management pages they should be able to apply that knowledge throughout OpenACS without additional learning.

10.0.5

Programmers should be able to regard AMS as an abstraction of the CR such that generic content browsers should provide meaningful information about AMS managed data hierarchies. Programmers should also be able to regard AMS as an abstraction of ACS Templating (including specific support for ad_form, list builder, acs widgets and Jon Griffin’s new paginator).

10.5 Programmer's API

It must be easy to use/integrate the AMS with any application or to add it in. This implies a stable, simple, and comprehensive API for programmers to use when writing or converting modules.

10.5.1 Data Specification Publishing

AMS must be able to pass on information about data sources on demand so that logic code and presentation layers can be built to be adaptable.

10.5.2 Validation of User Specified Structures

AMS must be able to gather and deliver the data that the data specification promises. This means that if a user is permitted by AMS to change/add/delete an attribute then there must be no errors thrown when data is requested from that attribute.

10.5.3 Obsolescence of Data

AMS must be able to handle discontinued, deleted or obsolete data in accordance with the logging behaviour specified by the user at custom attribute creation time. AMS must handle intelligently the situation where the user wishes to change the logging behaviour of a data item.

10.5.4 Customised Data Structure Changes

AMS must be able to permit attributes that have not been associated with a record to be associated with a record at a later date (and vice versa). This should serve as a mechanism for altering revision behaviour, and as a means of grouping already stored attribute data together into useful effective ‘tables’. Where logging has already occurred at attribute level, this is to be discarded when the attribute is allocated to a record. Where an attribute is moved from a record to become independently revision logged, there will similarly be no historical information available.

10.5.5 Recreation of ‘points in time’

For independent attributes AMS will be able to provide the recorded ‘live’ attribute value for any point in time since attribute definition. Any time point outside the range of the logged values should return ‘undef’. For attributes grouped into AMS records the recorded ‘live’ revision of the entire record will be available.

·        11.0 Usability

Programmers should be able to develop default data structure specifications using their standard tools for writing and maintaining code on the server.

VI.B Non-functional Requirements

·        100.0 Distribution

It must be possible to release AMS both as part of the ACS and as a separate module. When distributed as part of the ACS, all documentation, examples, and source code must follow ACS standards. This includes but is not limited to using the db_api, ad_page_contract, list builder and ad_form appropriately.

·        110.0 Performance

The AMS must not cause any performance problems to a site. It must be fast and efficient, and it must not slow down page load speed by more than 10% versus a standard Content Repository attributes implementation.

VII. Revision History

Document Revision #
Action Taken, Notes
When?
By Whom?

0.1
Creation
22/11/04
Richard Hamilton