@creation-date 2001-08-28
@cvs-id $Id$
}
ad_proc -private acs_reference_get_db_structure {
{-table_name:required}
} {
Query the DB to get the data structure. Utility function.
} {
}
acs-reference-4b204416c835e17792fc52462e6d6376bc3b7886/www/ 0000775 0000000 0000000 00000000000 10231023427 0021474 5 ustar 00root root 0000000 0000000 acs-reference-4b204416c835e17792fc52462e6d6376bc3b7886/www/doc/ 0000775 0000000 0000000 00000000000 10231023427 0022241 5 ustar 00root root 0000000 0000000 acs-reference-4b204416c835e17792fc52462e6d6376bc3b7886/www/doc/design.html 0000664 0000000 0000000 00000005471 10231023427 0024407 0 ustar 00root root 0000000 0000000
acs-reference Design Documentation
acs-reference Design Documentation
I. Essentials
- There is no user accessible directory
- There is no sub-site admin accessible diretory
- Requirements document: Requirements
- Data model:?? where does this really go?
- ER diagram: None yet
II. Introduction
Reference data is often overlooked in the rush to get coding. In reality, much of ....
III. Historical Considerations
Before the existence of acs-reference, the ACS required that you preload some tables in a script to get some basic reference functionality. There were many problems with this:
- No easy way to find out what reference data even existed.
- No way to find out how old the data was.
- No way to find out where that data came from.
- Very US/English slant on the data.
IV. Competitive Analysis
The only real competition is internally developed solutions.
V. Design Tradeoffs
Primary Goals
- This system was designed with maintainability and reusability as its primary goals. By wrapping a layer around all of the reference tables we have increased the maintainability immensely.
- Another goal was to bring together many different types of data and present them in a logical fashion. It was amazing how little of this data is available on the internet in a database friendly form.
Performance
When updating the reference tables their is overhead due to the fact that the table is registered with the repository. This should rarely occur anyway as the tables are only added once.
By not having the actual data itself in the acs-object system, subsequent additions and deletions to the reference tables themselves are unaffected by this overhead.
VI. API
VII. Data Model Discussion
VIII. User Interface
Their is no end user interface.
There will
IX. Configuration/Parameters
None
X. Future Improvements/Areas of Likely Change
A server based update mechanism will be supported. This will allow for tables to be updated (and preferably diffed) instead of being reloaded with a package upgrade.
An interface to produce xml/csv from the reference data would be a nice service to the community (allowing legacy applications a way to import this data).
XI. Authors
XII. Revision History
$Log$
Revision 1.1 2001/04/22 00:53:12 jong
initial openacs import
Revision 1.2 2000/12/13 04:39:00 jong
Added Revision History and corrected typo in reference link
acs-reference-4b204416c835e17792fc52462e6d6376bc3b7886/www/doc/index.html 0000664 0000000 0000000 00000001074 10231023427 0024240 0 ustar 00root root 0000000 0000000
ACS Reference Documentation
ACS Reference Documentation
Engineering Docs
Current docs are always at:
jongriffin.com
Release Notes
Please file bugs in the SDM.
jon@jongriffin.com
acs-reference-4b204416c835e17792fc52462e6d6376bc3b7886/www/doc/requirements.html 0000664 0000000 0000000 00000013542 10231023427 0025657 0 ustar 00root root 0000000 0000000
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
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
$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