Table of Contents
OffstageArts is an enterprise arts management system. It integrates
all aspects of a typical performing arts organization in one place:
development, marketing, school and ticket sales. For more information,
see: http://offstagearts.org.
OffstageArts is a Free Software aplication, licensed under the GPLv3. All components it uses, along with the devlopment tools needed to create it, are also free software. No commercial licenses are required to run or develop OffstageArts.
OffstageArts is implemented as a two-tier client-server database application, plus some web-based components. The server runs on the PostgreSQL database. The client, meant to be run by organizational staff, is at Java Swing application. Portions of OffstageArts --- those used directly customers --- are also web-based, written in Ruby.
Since is build on top of commodity components and protocols, it may be deployed in a flexible manner. The database may be accessed over a LAN or WAN, and the web server components may be deployed in a variety of manners. Technical consulting firms are able to determine and implement the best configuration for any particular organization.
Table of Contents
The following tools are required to download, compile, edit and install OffstageArts. Please download and install each of them on your system:
A Subversion client. Although it is not free as in freedom, we
recommend SmartSVN:
http://www.syntevo.com/smartsvn/index.html.
Java JDK version 1.5:
http://java.sun.com/javase/downloads/index_jdk5.jsp.
OffstageArts does not work with Java
1.6.
NetBeans 6.0 or 6.1: http://www.netbeans.org/. As a
Swing-based application, OffstageArts makes extensive use of the
visual form builder in NetBeans. Eclipse unfortunately does not have
a well-developed visual builder.
Apache Maven build tool version 2:
http://maven.apache.org/. We use Maven because of its
excellent dependency resolution. A command line-based Maven is
required, in addition to the one built into NetBeans.
This document was created using the DocBook 5+ XML DTD in the
XMLMind XML editor (Personal Edition):
http://www.xmlmind.com/xmleditor/download.shtml. It is
also not free as in freedom, but it is an excellent GUI-based
product.
After downloading and installing the above tools, it is necessary to configure them.
Maven:
Make sure you have Maven installed such that the command "mvn" works from your command shell.
NetBeans:
Make sure you make available to NetBeans the Java sources and Javadoc for your version of the JDK. This will allow NetBeans to give context-sensitive documentation help, as well as to take you to the source code of Java platform classes when you Ctrl-click on them. To integrate Java sources and Javadoc, start NetBeans and go to Tools->Java Platform.
Set up tab sizes: Go to Tools->Options->Editor->Indentation. Un-check 'Expand Tabs to Spaces." Set "Number of Spaces per Indent" and "Tab Size" both to 4.
If you are behind a firewall, configure your HTTP proxy via Tools->Options->General.
Get the Maven Plug-in: Go to Tools->Plugins->Available Plugins. If your HTTP proxy settings are not set right, you will see a blank screen. Once you see something, make a checkmark by "Maven" and click the "Install" button on the lower-left. Follow instructions.
SmartSVN:
Add the source code repositories to your system.
Repository->Mange Profiles->Add.
Click on "Enter SVN URL".
Enter
http://svn.berlios.de/svnroot/repos/holyokefw
Do the same for:
http://svn.berlios.de/svnroot/repos/offstagearts
OffstageArts depends on a large number of independent projects. Two of those are downloaded in source code format along with OffstageArts; the rest are available as JAR files either from the standard Maven repository, or are included in the source trees.
Three source-based NetBeans/Maven projects are required to compile and run OffstageArts. These can be obtained by checking out the following source code modules into one directory (say, ~/mvn):
trunk/offstagearts from the offstagearts
repository.
trunk/holyokefw from the holyokefw
repository.
trunk/holyokewiz from the holyokefw
repository.
trunk/holyokereports from the holyokefw
repository.
trunk/objcobra from the holyokefw
repository.
trunk/stringtemplate from the holyokefw
repository.
Once you have downloaded all source code, use File->Open Project on the downloaded project directories. If NetBeans does not recognize them as project directories, you might not have your Maven option installed. With all three projects open, set offstagearts as the main project in NetBeans: right-click on it and choose "Set as Main Project."
Now, run the following commands to install required JAR files into your Maven repository. (You may use Cygwin on Windows, or rename the install.sh files to Windows .bat files).
cd ~/mvn/objcobra/lib sh ./install.bat cd ~/mvn/holyokefw/lib sh ./install.bat cd ~/mvn/offstagearts/lib sh ./install.bat
The Holyoke Framework provides a set of typed widgets that subclass from standard Swing widgets and allow for the easy creation of GUI screens. In order to see the typed widgets in the NetBeans visual builder, they must be compiled as a .nbm module and loaded into NetBeans. This is accomplished as follows:
Clean and compile stringtemplate.
Clean and compile objcobra.
Clean and compile holyokefw.
Right-click on offstagearts in the "Projects" tabe of NetBeans and select "Set as Main Project."
Run the project (F6 in NetBeans).
Select MakeNbm from the dialog box that
appears.
When it is done running, you should now have the file
~/mvn/holyokefw/target/holyokefw-1.0-SNAPSHOT.nbm.
In NetBeans, use Tools->Plugins->Downloaded. Click on the "Add Plugins..." button. Select the .nbm file created above. Then click on the "Install" button in the lower left hand corner.
OffstageArts requires a database hosted on a server running PostgreSQL version 8 or higher. When installing your PostgreSQL database server for the first time, two configuration files need to be set up properly:
pg_hba.conf: This configures how PostgreSQL
authenticates the various users. The user named "postgres" is the
superuser for the database system. Depending on your installation
requirements, you may wish to set up different forms of
authentication. On a development laptop, it would be normal to use
"trust" authentication.
postgresql.conf: The option
"listen_addresses" in this file determines the IP address of clients
that will be allowed to connect to PostgreSQL. This should be
configured to allow connections from any clients that would be running
OffstageArts.
The script serverscripts/newuser.sh creates a
new user and database, ready for OffstageArts; see the script for details
on command line arguments. A few notes:
By convention, we create OffstageArts users and databases in
PostgreSQL using the same name. Thus, the database "tinytheater" is
associated with the user "tinytheater."
newuser.sh sfollows these conventions
newuser.sh requires that the postgres user
authentication be set to "trust." If this is not the case for your
PostgreSQL, a little bit of modification may be
necessary
newuser.sh creates essentially a blank database. The OffstageArts client fills in the schema as needed.
Finally, some people have reported problems with PostgreSQL version 8.3 with some applications. If you have problems with version 8.3, please try 8.2 or 8.1 instead.
Table of Contents
NOTE: This schema is out of date. Tables have been added and removed.
The main table to store each person or organization's record.
Subclasses from entities. This subclassing is obsolete. All entities are actually stored in the persons table. The isorg column indicates whether or not it is an organization. The persons table should be merged into entities.
A group is a set of entities, with additional meta-data identifying the set. Examples might include the set of students enrolled in a particular class, the set of people who attended a particular event, or the set of people who are donors.
Alternately, groups may be seen as a way to annotate individual entity records. For example, each phone type (home, work, cell, etc) is defined a groupid. Membership in the home "group" is used to indicate that someone has a home phone number.
Groups are defined in two tables. The group-wide meta-data describing the nature of the group is stored in groupids. Membership in the group, along with data attached to each entity's membership, is stored in groups.
All groupings in the database subclass groupids and groups in a predictable manner (see below).
Meta-data defining mail preferences in entities.
Storage for Offstage user-generated queries.
Below are the grouping tables, used to annotate entity records:
OffstageArts is able to keep running accounts for each entity. It stores multiple accounts per entity; the account types available are defined in actypes.
Each account consists of a balance record, describing the account balance at a point in time, followed by a series of transaction records, which change the account. Balance records may be made at any point the system feels is convenient. They should be seen as an optimization, so that the system does not have to sum all the transaction records from the beginning.
Balances
Transaction superclass
Types of accounts --- School, Tickets, Donations, etc.
Term bill transactions placed on the accounts. These records are automatically generated by the tuition calculator --- and also automatically revised if enrollment information is modified.
Manual adjustments to account --- used only for special cases
Record of cash payments
Record of credit card payments. A little more work needs to go into recording the status of credit card payments as they move through the validation process.
Record of check payments
For systems in which credit cards are batch processed, this indicates the batches in which they were processed.
Defines the terms the school goes through --- Fall 2008, Nutcracker 2007, Summer 2009, etc.
Different kinds of terms --- Fall, Spring, Summer, Nutcracker, etc. Annotates termids.
The dates at which different kinds of term bill payments are due --- whether they're quarterly, yearly, monthly, etc. The codes in this table ('y', 'q1', etc.) are referenced in the Java tuition calculation code.
Combined with the start and end date of a term in termids, the holidays table is used to define a school calendar. This is used to automate the filling in of the meetings table.
Lists the courses offered on a particular term.
Lists all the times a course meets over the course of a term.
Enrollments associates entities with courses, thus enrolling a person in a course. Enrollment in a course can involve peole in different roles --- which might include student, pianist, or teacher. Thus, it is not just students who get enrolled.
Record of pre-arranged class substitutions --- or viewed another way, this table allows students/teachers/pianists to enroll (or un-enroll) in a course on a meeting-by-meeting basis. The enrollment for any particular meeting is thus defined by enrollments table, with overrids from subs.
An open class program will involve an enrollments table with teacher and maybe pianist, but no permanent student enrollment. Students will be put in the subs table on a per-class basis.
Attendance record. Taken automatically or semi-automatically from information obtained at front desk.
A record of any unexplained absences noticed by the system (as obtained from the attendance table), plus what was done about them.
Courses may be grouped into sets, by level. In general, a student a particular level (in entities_school) should only be enrolled in level-appropriate courses. This information can be used to streamline the backoffice interface, and also limit options for parents on the web interface.
Meta-data table describing a number of different grade levels. Used in entities_school.
Meta-data describing the different programs (levels) at the school. Eg: Pre-Ballet I, Level IV, etc.
Students are typically allowed to register for a particular level (program) only after an audition. This table records their eligibility, thus allowing automated school registration, post-audition. Not yet used.
Before a student can be enrolled in courses, that student must be registered for a term. This table includes columns specific to a student on a per-term basis.
Per-term information for the payer of a student.
OffstageArts maintains a system of versioned resource in the database. These resources consist of report templates, and even the database schema itself. Resources have a version number (corresponding with the SVN version number of the code), as well as an overion number (which corresponds to a term or season, for resources that get their text changed every term or season.)
Names of the various resources the system keeps (versioned) track of.
The actual resources, as well as versioning information (both by version and oversion).
Information that will allow entities (typically parents) to log in via the web. Not yet used
In theory, OffstageArts client knows which user is using the system, based on Macintosh/Windows logins. It does not seem to work on Windows, and needs further testing.
This information can be used to restrict end-user access to certain OffstageArts functions. Currently, all functions are available to everyone.
The duplicate finder program stores its results here.
A log of merged records in pursuit of elimination of duplicates. Also indicates records that the duplicate finder thinks are duplicates, but actually are not --- telling the system to ignore those particular duplicates in the future.
A log of all insert and update queries to the core CRM tables (and maybe some others). It includes most changes to the database, but not all.
Conversions between days of the week in various forms. Shortcut to allow this table lookup via an SQL join.
Studio or Venue locations. Not sure if this is being used anywhere.