ACS Reference Requirements

Index: openacs-4/packages/acs-reference/www/doc/requirements.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-reference/www/doc/requirements.html,v diff -u -r1.1 -r1.2 --- openacs-4/packages/acs-reference/www/doc/requirements.html 22 Apr 2001 00:53:12 -0000 1.1 +++ openacs-4/packages/acs-reference/www/doc/requirements.html 6 Aug 2006 18:41:43 -0000 1.2 @@ -1,129 +1,141 @@ - - -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. - -

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. Revision History

- -

+
+
+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$
+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
-
-
-
-
-
-
-
+
+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
+

+ + +