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:
<h3>II. Introduction</h3>
</p>
Reference data is often overlooked in the rush to get coding. In reality, much of ....
<ul>
<h3>III. Historical Considerations</h3>
<li>No easy way to find out what reference data even existed.</li>
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:
<li>No way to find out how old the data was.</li>
<ul>
<li>No way to find out where that data came from.</li>
<li>No easy way to find out what reference data even existed.</li>
<li>Very US/English slant on the data.</li>
<li>No way to find out how old the data was.</li>
</ul>
<li>No way to find out where that data came from.</li>
<h3>III. Design Tradeoffs</h3>
<li>Very US/English slant on the data.</li>
<h4>Primary Goals</h4>
</ul>
<ul>
<h3> IV. Competitive Analysis</h3>
<li>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.</li>
The only real competition is internally developed solutions.
<li>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.</li>
<h3> V. Design Tradeoffs</h3>
</ul>
<h4>Primary Goals</h4>
<h4>Performance</h4>
<ul>
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.
<li>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.</li>
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.
<li>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.</li>
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.
<p>The UNSPSC reference data has a data model for handling data
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.
revisions. An application can determine any new/revised category based
<h3> VI. API</h3>
on existing, obsolete data.</p>
<h3> VII. Data Model Discussion</h3>
<h3>VI. User Interface</h3>
<h3> VIII. User Interface</h3>
<p>Their is no end user interface.
Their is no end user interface.
There needs to be some kind of admin UI to report status and possibly
There will
manage updates per requirements.
<h3> IX. Configuration/Parameters</h3>
</p>
None
<h3>VII. Configuration/Parameters</h3>
<h3> X. Future Improvements/Areas of Likely Change</h3>
<p>None</p>
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.
<h3>VIII. Future Improvements/Areas of Likely Change</h3>
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).
<p>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.
<h3> XI. Authors</h3>
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).
<h3> XII. Revision History</h3>
</p>
<pre>
<h3>IX. Authors</h3>
<p>
Jon Griffin
</p>
<h3>X. Pre-CVS Revision History</h3>
<pre>
$Log$
$Log$
Revision 1.4 2006/08/06 20:40:20 torbenb
upgrading html, closing li p tags, adding quotes to tag attributes
This document describes the requirements for the ACS Reference service
<h3>I. Introduction</h3>
package. This package has the following primary functions:
<p>This document describes the requirements for the ACS Reference service
<ul>
package. This package has the following primary functions:
<li>It allows applications to refer to and employ a common set of reference
</p>
data.</li>
<ul>
<li>It gives administrators the ability to run standard reports on this data.</li>
<li>It allows applications to refer to and employ a common set of reference
<li>It offers a convenient repository for and the ability to run reports on
data.</li>
data of this sort.</li>
<li>It gives administrators the ability to run standard reports on this data.</li>
<li>It allows us to monitor the usage of reference data.</li>
<li>It offers a convenient repository for and the ability to run reports on
</ul>
data of this sort.</li>
<h3>II. Vision Statement</h3>
<li>It allows us to monitor the usage of reference data.</li>
<p>What is reference data? Simply put, it is data that doesn't change
</ul>
very often and also in many cases comes from an external source and not
<h3>II. Vision Statement</h3>
from within the system itself. Many times it is created from a standards
<p>What is reference data? Simply put, it is data that doesn't change
body, i.e. <ahref="http://www.iso.ch/">ISO</a> or <ahref="http://www.ansi.org">ANSI</a>, and may be required for a client's particular industrial needs.
very often and also in many cases comes from an external source and not
<p>Some examples of reference data are:
from within the system itself. Many times it is created from a standards
<ul>
body, i.e. <ahref="http://www.iso.ch/">ISO</a> or <ahref="http://www.ansi.org">ANSI</a>, and may be required for a client's particular industrial needs.
<li>Geographic data: zip codes, country codes and states/provinces</li>
</p>
<li>Standards bodies data: ISO 4217 currency codes, ISO 3166 Country Codes, ITU
data models simply defer the issue by treating reference data as
<li>Internal: Status Codes, Employee Position Codes</li>
something simple to implement. Elsewhere. The reality is
</ul>
that for most organizations reference data is extremely important and
<p>Historically, reference data has been looked upon by developers as
also extremely difficult to manage.
something less important than more immediate coding needs, and so most
<p>This module will not only <i>package</i> all of a site's reference
data models simply defer the issue by treating reference data as
data in one place, it will also help manage that data.
something simple to implement. Elsewhere. The reality is
<h3>III. System Overview</h3>
that for most organizations reference data is extremely important and
The ACS Reference package consists of:
also extremely difficult to manage.
<ul>
</p>
<li>A standard framework for monjitoring and modifying reference data.
<p>This module will not only <i>package</i> all of a site's reference
<li>A method of determining whether or not that data is expired.
data in one place, it will also help manage that data.
<li>The ability to include not only the data but also functions to
</p>
work with that data.
<h3>III. System Overview</h3>
</ul>
<p>The ACS Reference package consists of:</p>
<h3>IV. Use-cases and User-Scenarios</h3>
<ul>
Papi Programmer is developing a module that will use country codes as
<li>A standard framework for monjitoring and modifying reference data.</li>
part of his table structure. Instead of creating his own table he can
<li>A method of determining whether or not that data is expired.</li>
use the ACS Reference package and the country codes therein. If the
<li>The ability to include not only the data but also functions to
country codes change - which does in fact happen from time to time -
work with that data.</li>
the ACS Reference package will maintain that information for him.
</ul>
<h3>V. Related Links</h3>
<h3>IV. Use-cases and User-Scenarios</h3>
<ul>
<p>Papi Programmer is developing a module that will use country codes as
<li><ahref=design.html>Design document</a>
part of his table structure. Instead of creating his own table he can
</ul>
use the ACS Reference package and the country codes therein. If the
country codes change - which does in fact happen from time to time -
<h3>VI.A Requirements: Data Model</h3>
the ACS Reference package will maintain that information for him.
</p>
10.10 The package should use a table that is the <i>master</i> table for all reference tables.
<h3>V. Related Links</h3>
<br>10.20 The package should employ a field to show whether this data is internally derived or not.
<ul>
<br>10.30 The package should employ a field to signify whether there is a PL/SQL package involved with
<li><ahref="design.html">Design document</a>
this table.
</li></ul>
<br>10.40 The package should offer an indicatation of when this data was last updated.
<br>10.50 The package should offer an indication of what the original source of this data was.
<h3>VI.A Requirements: Data Model</h3>
<br>10.60 The package should offer an indication of what the original source URL was, if any.
<p>
<br>10.70 The package should offer a representation of effective datetime
10.10 The package should use a table that is the <i>master</i> table for all reference tables.
<br>10.80 The package should offer a representation of discontinued datetime
<br>10.20 The package should employ a field to show whether this data is internally derived or not.
<br>10.90 The package should keep an indication of who the data maintainer is, by user_id.
<br>10.30 The package should employ a field to signify whether there is a PL/SQL package involved with
this table.
<h3>VI.B Requirements: API</h3>
<br>10.40 The package should offer an indicatation of when this data was last updated.
<br>10.50 The package should offer an indication of what the original source of this data was.
20.10 The package should offer a function to determine if a particular table has expired.<p>
<br>10.60 The package should offer an indication of what the original source URL was, if any.
<br>10.70 The package should offer a representation of effective datetime
The requirements below are not met by the current implementation:<p>
<br>10.80 The package should offer a representation of discontinued datetime
<br>10.90 The package should keep an indication of who the data maintainer is, by user_id.
30.10 There needs to be a way to query the data source and update
</p>
automatically. If that isn't possible, as it won't be in many cases,
<h3>VI.B Requirements: API</h3>
the application should be able to query a master server and see if
<p>
there is new data for a particular table or tables. For example:
20.10 The package should offer a function to determine if a particular
refdata.arsdigita.com could hold the reference tables and when newer
table has expired.
table versions become available, simply upload only these versions or
</p><p>
perhaps even only the differences between the tables.
The requirements below are not met by the current implementation:
</p><p>
<h3>VII. Implementation Notes</h3>
30.10 There needs to be a way to query the data source and update
The package needs to handle changes to reference data in a graceful
automatically. If that isn't possible, as it won't be in many cases,
fashion. For example, if a country splits into two or more countries, what should happen?
the application should be able to query a master server and see if
<ul>
there is new data for a particular table or tables. For example:
<li>The reference package should note this change.</li>
refdata.arsdigita.com could hold the reference tables and when newer
<li>The appropriate table is updated. In this case countries et al.</li>
table versions become available, simply upload only these versions or
<li>An update to the repository database field effective_date is added.</li>
perhaps even only the differences between the tables. In any case,
<li>A <i>diff</i> type of entry into the reference repository history. <fontcolor = "red"><i>This is not in the current data model</i></font>
there should be an admin page that shows current status and revisions
<li>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).</li>
of various data, where to find info about additional sources (if
<li>Historical data will be available using this <i>diff</i> for those applications that need to use the old data</li>
applicable), and provide a UI to upload or import new data.
</ul>
</p>
Note also that it is possible to have overlapping effective dates.
<h3>VII. Implementation Notes</h3>
This will not be implemented in the first version, but should be recognized and accomodated throughout the development
<p>
process for the service package.
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?
<h3> VIII. Revision History</h3>
</p>
<ul>
<pre>
<li>The reference package should note this change.</li>
<li>The appropriate table is updated. In this case countries et al.</li>
<li>An update to the repository database field effective_date is added.</li>
<li>A <i>diff</i> type of entry into the reference repository history. <fontcolor = "red"><i>This is not in the current data model</i></font></li>
<li>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).</li>
<li>Historical data will be available using this <i>diff</i> for those applications that need to use the old data</li>
</ul>
<p>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.
</p>
<h3> VIII. Pre-CVS Revision History</h3>
<pre>
$Log$
$Log$
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
