Index: openacs-4/packages/acs-reference/www/doc/requirements.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-reference/www/doc/requirements.adp,v diff -u -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-reference/www/doc/requirements.adp 27 Oct 2014 16:39:43 -0000 1.2 @@ -0,0 +1,116 @@ + +{/doc/acs-reference {ACS Reference Data}} {ACS Reference Requirements} +ACS Reference Requirements + + + +

ACS Reference Requirements

by Jon Griffin +

I. Introduction

This document describes the requirements for the ACS Reference +service package. This package has the following primary +functions:

It allows applications to refer to and employ a common set of +reference data.
It gives administrators the ability to run standard reports on +this data.
It offers a convenient repository for and the ability to run +reports on data of this sort.
It allows us to monitor the usage of reference data.

II. Vision Statement

What is reference data? Simply put, it is data that doesn't +change very often and also in many cases comes from an external +source and not from within the system itself. Many times it is +created from a standards body, i.e. ISO or ANSI, and may be required for a client's +particular industrial needs.

Some examples of reference data are:

Geographic data: zip codes, country codes and +states/provinces
Standards bodies data: ISO 4217 currency codes, ISO 3166 +Country Codes, ITU Vehicle Signs
Quasi-Standards: S&P Long-term Issuer Credit Ratings
Internal: Status Codes, Employee Position Codes

Historically, reference data has been looked upon by developers +as something less important than more immediate coding needs, and +so most data models simply defer the issue by treating reference +data as something simple to implement. Elsewhere. The reality is +that for most organizations reference data is extremely important +and also extremely difficult to manage.

This module will not only package all of a site's +reference data in one place, it will also help manage that +data.

III. System Overview

The ACS Reference package consists of:

A standard framework for monjitoring and modifying reference +data.
A method of determining whether or not that data is +expired.
The ability to include not only the data but also functions to +work with that data.

IV. Use-cases and User-Scenarios

Papi Programmer is developing a module that will use country +codes as part of his table structure. Instead of creating his own +table he can use the ACS Reference package and the country codes +therein. If the country codes change - which does in fact happen +from time to time - the ACS Reference package will maintain that +information for him.

V. Related Links

Design document

VI.A Requirements: Data Model

10.10 The package should use a table that is the master +table for all reference tables.
+10.20 The package should employ a field to show whether this data +is internally derived or not.
+10.30 The package should employ a field to signify whether there is +a PL/SQL package involved with this table.
+10.40 The package should offer an indicatation of when this data +was last updated.
+10.50 The package should offer an indication of what the original +source of this data was.
+10.60 The package should offer an indication of what the original +source URL was, if any.
+10.70 The package should offer a representation of effective +datetime
+10.80 The package should offer a representation of discontinued +datetime
+10.90 The package should keep an indication of who the data +maintainer is, by user_id.

VI.B Requirements: API

20.10 The package should offer a function to determine if a +particular table has expired.

The requirements below are not met by the current +implementation:

30.10 There needs to be a way to query the data source and +update automatically. If that isn't possible, as it won't be in +many cases, the application should be able to query a master server +and see if there is new data for a particular table or tables. For +example: refdata.arsdigita.com could hold the reference tables and +when newer table versions become available, simply upload only +these versions or perhaps even only the differences between the +tables. In any case, there should be an admin page that shows +current status and revisions of various data, where to find info +about additional sources (if applicable), and provide a UI to +upload or import new data.

VII. Implementation Notes

The package needs to handle changes to reference data in a +graceful fashion. For example, if a country splits into two or more +countries, what should happen?

The reference package should note this change.
The appropriate table is updated. In this case countries et +al.
An update to the repository database field effective_date is +added.
A diff type of entry into the reference repository +history. This is not in the current data +model +
Then any sub-programs using this data will note the change of +effective date and be able to handle the change as needed (i.e. +simply read the new table).
Historical data will be available using this diff for +those applications that need to use the old data

Note also that it is possible to have overlapping effective +dates. This will not be implemented in the first version, but +should be recognized and accomodated throughout the development +process for the service package.

VIII. Pre-CVS Revision History

+$Log: requirements.adp,v $
+Revision 1.1.2.1  2014/09/17 18:35:54  gustafn
+- prettify documentation (use master templates)
+
+Revision 1.3  2006/08/06 20:40:20  torbenb
+upgrading html, closing li p tags, adding quotes to tag attributes
+
+Revision 1.2  2006/08/06 18:41:43  torbenb
+removed c-Ms, added p tags, added a comment to unimplemented requirements / feature request
+
+Revision 1.1  2001/04/22 00:53:12  jong
+initial openacs import
+
+Revision 1.7  2000/12/15 04:09:25  jfinkler
+fixed numbering scheme
+
+Revision 1.6  2000/12/13 04:33:47  jong
+Updated doc for alpha release
+
+Revision 1.5  2000/12/12 06:29:21  jfinkler
+spelling error, my fault
+
+Revision 1.4  2000/12/12 06:28:05  jfinkler
+fixed a few formatting errors
+
+Revision 1.3  2000/12/12 06:26:20  jfinkler
+reorganized content, edited for clarity
+
+Revision 1.2  2000/12/08 02:41:31  ron
+initial version
+