Forum OpenACS Development: A useful (but buried) aD URL for module porting info

Don't know if you all already know about this, but I just stumbled upon
http://www.arsdigita.com/doc/design/, which seems to have the design
docs for the majority of the 4.x modules, plus links to overviews,
requirements, page flow documentation, ER-diagrams (whatever the heck
they are), and other stuff that looks like it could be useful.
Collapse
Posted by Albert Langer on
The link Michael Feldstein gave is actually for ACS 3
documentation, not ACS4:

https://openacs.org/bboard/q-and-a-fetch-msg.tcl?msg_id=0001ZP&topic_id=12&topic=OpenACS%204%2e0%20Design

I'm also cross-posting this to parallel discussion of possible
python and Zope ecommerce using OpenACS4 data model in zcommerce list:

http://lists.codeit.com/mailman/listinfo/zcommerce

As Michael mentioned there are separate sections for different
types of ACS3 documentation:

http://www.arsdigita.com/doc/overviews/

http://www.arsdigita.com/doc/design/

http://www.arsdigita.com/doc/requirements/

http://www.arsdigita.com/doc/page-flow/

http://www.arsdigita.com/doc/er-diagrams/

BTW the ER diagrams are incredibly cluttered and look like
were just auto-generated with the SQL. I think proper UML
diagrams from various viewpoints would be much more useful.
They are supposed to *explain* the SQL DDL but don't really
achieve that.

The page flow diagrams are slightly more useful for
explaining the connection between tcl files and web
pages.

Above are certainly very useful, eg for the ecommerce 3 module
already ported to OpenACS 3 and ACS4 and now being ported back to
OpenACS4. Since it's already been done for both OpenACS 3 and ACS 4
I imagine the people doing that already know all there is to know
about it. However I'm particularly concerned about the possibility
of needing to use parts of it, such as customer service, together
with the skeleton for ecommerce4 to meet interim needs for
something that can handle multiple vendors while waiting for
more of ACS ecommerce 4. Pretty well anything that uses billing
and order processing also needs customer service linked to them,
so that may be needed before ecommerce 4 is available.

So I've been trying to collect as much doc info on both ecommerce3
and ecommerce4 as possible. See notes below.

BTW can anyone offer *any* sort of hints as to when just a sneak
peak at the ecommerce 4 sql data models might be possible?

Ditto for credit card payments protocols implementation. With
cybercash already bankrupt others will also be necessary
and it would be a shame if the work being done for protocols to
work with ecommerce3 on openacs4 had to be redone for ecommerce4
(thus also affecting aD as well as openacs).

The page flow diagrams for ecommerce 3 (including customer service)
are missing from above.

They can be obtained directly from the cvs:
http://cvs.arsdigita.com/cgi-bin/cvsweb.pl/acs3x/www/doc/ecommerce/

These two are the actual .pdf files for users and admin interactions
respectively:

http://cvs.arsdigita.com/cgi-bin/cvsweb.pl/~checkout~/acs3x/www/doc/ecommerce/ecommerce_interaction_users.pdf?rev=1.1&content-type=text/plain

http://cvs.arsdigita.com/cgi-bin/cvsweb.pl/~checkout~/acs3x/www/doc/ecommerce/ecommerce_interaction_admin.pdf?rev=1.1&content-type=text/plain

It might be worth checking the cvs for other missing documentation.

Together with above and the links within the pages below, following is a complete
list of the documentation I am aware for ecommerce3. The design and er-diagrams
are probably the most directly useful for porting:

http://www.arsdigita.com/doc/overviews/ecommerce

http://www.arsdigita.com/doc/design/ecommerce.html

http://www.arsdigita.com/doc/requirements/ecommerce

http://www.arsdigita.com/doc/er-diagrams/small_ecommerce_er.pdf

http://www.arsdigita.com/doc/overviews/customer-service.html

http://www.arsdigita.com/doc/design/customer-service.html

http://www.arsdigita.com/doc/requirements/customer-service.html

http://www.arsdigita.com/doc/er-diagrams/small_customerrepository_er

Actual code for both SQL and TCL can be inspected via the online
interfaces eg:
http://www.arsdigita.com/doc/sql/display-sql?url=/doc/sql/ecommerce.sql

In case they are helpful to anyone else, here are my notes
concerning ACS4 documentation, specifically focussed on
ecommerce4.

Starting point for anyone trying to get to grips with ACS is:

http://www.arsdigita.com/books/panda/

The general ACS documentation is available via:
http://developer.arsdigita.com/acs40-project-central

http://developer.arsdigita.com/doc/

Starting point for what's involved in ACS 4 is:

http://developer.arsdigita.com/doc/acs-dev.html

In particular the overview and kernel documentation.

Complete source for ACS 4.2 (Oracle/Tcl):
http://www.arsdigita.com/acs-repository/one-version?version_id=1781

The specifically "ecommerce" module is defined more narrowly by
ACS, designed to fit in with the rest of a "Community" system
that integrates some of the "magic". Actual order processing,
billing etc has not yet been released for ACS4, though a
"skeleton" alpha version for ACS4 Tcl is documented at:

http://developer.arsdigita.com/commerce-project-central/

Four downloads are available for alpha2:

http://developer.arsdigita.com/commerce-project-central/alpha2.html

billing-0.4d.apm
com-order-mgmt-0.3d.apm
com-order-constr-0.1d.apm
com-sample-site-0.3d.apm

No further releases for ACS4 Tcl are expected.

Two teams are currently working on the ACS4 java version.

The previous version for ACS3 ported to work on ACS4
is available from:

http://www.arsdigita.com/acs-repository/

Get both Ecommerce 4.1a:
http://www.arsdigita.com/acs-repository/one-version?version_id=1663
and ACS Geo-Tables 4.1a:
http://www.arsdigita.com/acs-repository/one-version?version_id=1664

It will be ported to OpenACS4 for use with PostgreSQL after the core
for that is done. This is the one mentioned at:

http://www.arsdigita.com/bboard/q-and-a-fetch-msg?msg%5fid=000b5M&topic%5fid

It will essentially have the same functionality
as the existing OpenACS3 version, but integrated
to work with OpenACS4.

There is also a separate Ecommerce-Lite demo, with does not actually
use the skeleton order-management, order-construction and billing modules
above, but provides a "demo" store with catalog.

The v1.0 has 2 small downloads for data model and storefront, plus
a third for demo-data which is 1.7MB of product photos.

When you don't have a running (Open)ACS installation the following
notes may also be useful.

Documentation is in [package]/www/doc/*.adp

The *.apm files are designed to install quickly
with an ACS system. The *.adp files within are
readable as text but designed for
formatted display by running system.

The *.sql files are the most relevant code for understanding
what it's about. More extensive requirements and
design docs for a package are often at the general
ACS project-central links above.

Just rename to *.tgz to extract the *.apm files.

The repository URL above also has the complete ACS Tcl
4.2 beta system itself, which OpenACS is porting from Oracle
to PostreSQL. aD development of this will stop after 4.3.

Also has the new ACS 4 java with the same SQL data model
which will be the basis for further aD development to ACS 5.

I believe the ACS workflow 4.3 (plus Workflow Sample
Application 0.1d) will also be very relevant to ecommerce.

OpenACS4 (under construction) includes much of the
documentation for ACS 4 within the
individual packages available from the cvs:

https://openacs.org/new-file-storage/download/cvs.html?version_id=140

However not all the design docs and diagrams available above
are included in the ACS 4 release packages.

Might be a good idea to add the separate design docs from aD web
site to the cvs so that they are readily available to developers
when they do cvs checkouts instead of having to look in 2 places.

If I've missed anything above (eg from ACS or openacs bboards)
I would appreciate it if somebody could supply the links.

Requirements & design docs for 4 are available from 4.0 project central and from the individual modules doc pages (no idea if one is more recent than the other):

Project Central:
http://acs40.arsdigita.com/acs40-project-central/qa-assignments.html

Individual doc pages:
Go to http://www.arsdigita.com/doc/ and pick a module, or "Kernel Documentation", from there you can see requirements and design for that package.

I do not believe E-R diagrams or page flow diagrams exist for 4.0.  The E-R diagrams for 3 were done from the SQL and hand edited/arranged; aD did not design with E-R diagrams (nor do I think they need to) and they didn't exist for 3 for quite a while (until many people insisted), partly because you tend to need a Windows box to generate them (aD has started moving towards having more people with Windows boxes on their desktop, so that might change as they become a more "traditional" company).  I believe UML is being done for 4.5, and the documentation for that is supposed to go public sometime soon (according to the conference call; I believe they had said next week on April 26th)