EUTC Wiki - User contributions [en]

User:Xander

2009-09-20T18:25:02Z

Xander: Updates for 09/10

== Xander Macmillan ==

I am a techie in the Bedlam Theatre.

I am working on and have worked on various tech and IT systems in the Bedlam Theatre at one time or another. As such if you have a query with regards to any of the below you should get in touch with me. This is especially true if you are planning to perform maintenance that may be better informed with some background knowledge about a projects' history.

== Involvement ==

=== Ex-projects and responsibilities ===

* Purchasing the '''[[Sound Desk|Soundcraft GB4]]'''
* Fixing '''Zero88 Betapacks''' on the cheap
* The '''Bedlam Fringe website''' - Sam is maintaining interim content on the [http://www.bedlamfringe.co.uk Bedlam Fringe website] until Fringe 2010. The 2009 website is archived [http://bedlamfringe2009.portfolio.x13n.com here].
* The '''Bedlam and EUTC website content and domain names''' - Luke is in charge of these now
* '''Bedlam and EUTC email addresses''' - Luke can help you fix these

=== Current projects and responsibilities ===

* The Bedlam and Bedlam Fringe hosting and webspace
* The Bedlam Fringe email addresses
* The tickets, ticketing software, ticket printer and online ticketing (http://opentheatre.org.uk)
* The Box Office and Cafe computers

== Contacting Me ==

I keep up-to-date contact information at [http://x13n.com/alex x13n.com/alex]. Get in touch with me about anything any time.

XTS

2009-02-27T12:03:28Z

Xander: Migrating content to opentheatre.org.uk

== XTS has a home! ==

Because XTS might be useful to other theatres and is taking code contributions from multiple people, XTS now has it's own website at http://www.opentheatre.org.uk. The content on this page is being migrated to the new site, where it should be better updated and made more comprehensive.

== eXtensible Ticketing System ==

XTS is the Bedlam Theatre's new ticketing system. It's key feature is extensibility, meaning that if it doesn't do something you want it to do, you (or a suitably inclined geek) should easily be able to add it. Read on for more key features and read further for technical information that will help you maintain and make changes to the system if that is your want.

If you are just looking for help using the software to sell tickets, try [[Using XTS]].

== What I planned to write about ==

* History / Motivation
* Things you should know before you start
** Key Concepts and Terminology
*** "Reserved" vs. "Booked".
*** "Holding" tickets.
*** "Ticket Prototypes"
*** Verifying bookings
*** "Snewts"
*** How XTS handles times between 0AM and 3AM.
** Principles
*** Portability (OS Transparency)
*** Accessibility (Network Transparency)
*** Extensibility
*** Readability
*** Simplicity (Minimum Complexity in the Layers that Matter)
*** High-Level Scripting
* Technologies in use
** HTTP
** XML
** HTML
** CSS
** Python
** Java
** Crypto - Rjindael (AES)
* Parts of the system
** DONE Database
*** DONE Scheduled Database Backup
** DONE Ticket Server
*** DONE Web.py
*** DONE API
** DONE Print Server
*** DONE API
*** DONE Making new ticket layouts
*** DONE Changing the ticket logo
** Static Server
*** Apache 2.2
** Administration Server
** Javascript Client
*** Ami
*** Snewts
*** Prism
** Reporting
*** XSLT
** HTTPProxy
*** Protecting the ticketing server from the proxy
** Startup - Windows Services
*** JSWrapper
* Directory Structure (C:\XTS\)
* Installing XTS
* Making Improvements - A HOWTO
** Known Issues / Things you might like to work on
*** Sniffing attacks
*** No test suite, no TDD
*** Transactions (there aren't any)
*** Printing - it's pretty crap
*** Reports - XSLT, but not as it should be
** Familiarisation
*** Grokking the Source
** Tools You Must Use
*** Firebug
*** IPython
** Things You Must Do
*** DONE Setting up your own dev version from trunk
*** Keeping the documentation up-to-date
** Safe and Unsafe
*** Where is the money?
** Versioning
** Fun Ideas For Improvements or Otherwise
*** Booking from portable devices for producers ("Would you like to come? I'll book you a ticket now.")
*** XTS-controlled DMX for Box Office Lighting Fun Times
*** Heads-up displays for show times and sold out info a-la every cinema you've ever been to

= Documentation =

== Parts of the System ==

=== Database ===

XTS uses a MySQL database. It should be very easy to port XTS to other databases, most access is abstracted through [[#web.py]]'s db module but there may be some report-generating SQL queries that are specific to MySQL in the XTS source. See [[#data.py]] for more info.

The schema is called "xts".

==== Scheduled Database Backups ====

As of 2008-07-18, [[Maude]] is configured to take nightly backups of the XTS database to C:\XTS\Backups. These backups should be scaled back to weeklies or slower at the end of Fringe 2008 or they '''will''' eventually consume all available disk space on the machine. Furthermore the database should occasionally be backed up "off-site" in case of hard disk failure.

=== Ticket Server ===

The ticket server does the hard work of allocating, booking and selling tickets of various types for various performances of various shows. The ticket server is written in [[#Python]]. It is implemented on top of a web server ([http://www.webpy.org web.py]]), allowing clients to interact with the server via [[#HTTP]] using [[#XML]] for data exchange.

The ticket server is accessible via HTTP on port 8080.

==== API ====

API stands for Application Programming Interface. It tells you how you can write programs that talk to the ticket server in order to do useful things (like get show information, or sell tickets online).

The [[#Javascript Client]] uses the XTS API to make a nice box office interface for selling tickets to customers.

If you know a little XML you can write programs that interact with the API yourself. You can write your programs in Java, PHP, Python, Ruby -- whatever. So long as you can make an HTTP connection and deal with a little XML, you're good to go.

See [[XTS API]] for further information and full documentation.

==== Security ====

The ticket server uses host and password authentication to decide who can do what using the API. Full details are in the [[XTS API|API documentation]].

XTS also has a built-in secure proxy (security.py, part of [[#XWF]]), based on AES with a preshared key. It allows trusted remote hosts privileged access to the ticketing server over an encrypted connection.

Applications that want to use the secure method of connecting to the server use a special URL (/v1/secure/v1/connect) and then "trade secrets" with the ticketing server in order to prove it's trustworthiness and verify the trustworthiness of the server. It's all very ingenious and you really shouldn't try doing it yourself until you've taken Computer Security (a really good course) or are Bruce Schneier.

To be honest, it's quite voodoo - but it's also crucial when doing anything regarding ticket sales over the internet. So, really, don't mess with it until you quite know what you're doing.

==== Error Handling ====

When the server encounters an error (for instance, a ticket that you are selling has already been sold), internally it throws a SnewtsError exception.

SnewtsErrors are caught by the request dispatcher (snewtsUrlInvocation in server.py) and turned into an XML-formatted error that is sent back to the client.

SnewtsErrors consist of an error number (useful to computers) and an error message (useful to people). Errors are grouped into types. For instance, all errors that start with the number 404 represent a requested thing not being there ("Not Found"). However, 404.1 specifically means that it was a ticket that wasn't found. 404.2 means a performance wasn't found and so on.

This is important when writing software that talk to the ticket server via the [[#API]]. When reading responses from the server the client software can have a default way of handling 404 errors but additionally can have a specific way of handling 404.5 errors.

Where possible, error numbers correspond to the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html HTTP status code definitions]. This is mostly because I'm perverse and think it's funny that when something isn't there you get a 404 error. However, it can be useful when writing your client software in that a 4xx error indicates that the client probably did something wrong whereas 5xx errors indicate that something went wrong on the server (which is potentially much more serious).

==== XWF ====

XWF is a python module of useful bits of code for writing web applications. The thinking is that only XTS code should be in the XTS module. So if there's some code which does something more generic - like writing log files or providing security - this code should be written in a different module where it doesn't clutter up the code that actually matters.

At time of writing, XWF includes xml.py, which is a lightweight set of functions for very quickly writing XML documents, and security.py, which provides a security layer for remote hosts that need trust and secrecy when talking to the Ticket Server (see [[#Security]]).

==== Source ====

Alphabetically:

===== constants.py =====

Contains various useful constants used in the rest of the XTS source. This makes the code more readable. In the database, the number 2 represents a ticket that is booked. However, instead of using the number 2 to refer to such tickets in the source code, we use the expression <code>ticketstates['BOOKED']</code>. This makes the code (a lot) more readable.

Funnily enough, it's generally a bad idea to change the constants. However, you should add to them where appropriate, for instance, if you intend to record new kinds of events in the log.

''There is nothing technically '''constant''' about the variables in constants.py - they could easily be modified at runtime. If you know how to define constants that are actually constant, or just of a better general approach, then this might be an area of the server that you could improve.''
--[[User:Xander|Xander]] 17:21, 18 July 2008 (BST)

===== data.py =====

data.py provides an interface to the database. Wherever XTS needs to get information from the database, it does it by calling a function in data.py. data.py then takes care of turning the information request into SQL, and if necessary, post-processing the response into a useful form for the caller.

You should be able to port XTS to another datastore simply by replacing data.py and stats.py.

===== exceptions.py =====

exceptions.py defines the SnewtsError exception type. For more information, see [[#Error_Handling]].

===== helpers.py =====

helpers.py contains various functions that help to solve common and recurring problems in the Snewts application (for instance, turning datetime objects into human-readable date strings). This unclutters [[#logic.py]], which should just contain the business logic of how to sell tickets properly. Functions in helpers.py should ideally be moved into [[#XWF]], but who really cares?

===== logic.py =====

logic.py sits between the client request and the database. When the client asks to sell a ticket, logic.py makes sure that the show actually exists, the ticket is valid for the performance, there are enough tickets left and anything else that needs making sure of. If any one bit of XTS is going to get something critically wrong, it's going to be in logic.py.

logic.py never talks to the database directly. To get data from the database and make changes to the database it must call functions in [[#data.py]].

===== printer.py =====

printer.py is an abstraction layer with one synchronous public function, printTicket(). It takes care of sending the ticket to the [[#Print Server]] and making sure that the printer got the ticket. If the print can't be confirmed it throws a SnewtsError.

===== reflection.py =====

reflection.py is a silly bit of code with some functions for counting lines in code. It's used to provide some of the statistics you get when you look at the XTS "about" page, such as how many TODO comments are still left in the code.

reflection.py should be refactored into the XWF module - none of the code is specific to XTS itself, so it shouldn't be cluttering up the snewts module.

===== report.py =====

report.py contains all of the code that formats statistics gathered from the database into XML reports. It also does a little math. See [[#Reporting]].

===== snewts.py =====

snewts.py does the job of recognising requests from clients, checking that the clients are authorised to make the requests, and sending back responses. Simple requests (ie. getPerformances) are fulfilled by getting data from [[#data.py]] directly. More complicated requests are fulfilled by calling business logic in [[#logic.py]] or getting [[#report.py]] to generate reports.

===== stats.py =====

stats.py contains code for calculating various metrics and statistics with regards to the XTS database (such as "how many tickets have been sold?" and "of all of the seats that have been available for all of the shows ever, what percentage of them did we actually sell?"). stats.py accesses the database directly, because otherwise all of the code in stats.py would have to be in data.py, and that would make data.py even bigger than it already is.

===== status.py =====

status.py contains definitions of all of the errors that XTS may reply with when something goes wrong. If you're writing client software, you need to anticipate these coming back at you.

=== Print Server ===

The print server is a separate entity from the ticketing server that handles ticket printing. It listens on the network for messages instructing it to print tickets.

It is written in pure Java for the convenience of Java's layout and printing library. It uses the effective users' default printer for printing (so this printer needs to be set to the ticket printer).

==== API ====

The print server listens for tickets to print on port . Tickets are sent to the printer as UDP messages on port 8301. The UDP message format consists of six strings terminated by the NULL character. It does not support UTF8 encoding. It is very fail. The strings are, in order:

* Show Name
* Date (expected format: ddd YYYY-MM-DD)
* Time (expected format: HH:MM)
* Booking name (can be an empty string)
* Ticket serial
* Ticket type (ie. "Student")

When the print server receives your ticket and succeeds in dispatching it to the printer it will reply with a UDP packet containing the ticket serial you specified.

==== Making new ticket layouts ====

You need to know Java to write new ticket layouts.

Make a pair of new classes implementing uk.org.opentheatre.xts.Ticket and uk.org.opentheatre.xts.TicketFactory. The former must lay out the ticket, the latter must create instances of the ticket. Look at existing ticket classes for examples on how to do this.

Then, modify the uk.co.bedlamtheatre.BedlamTicketPrintServer to use your new TicketFactory class. You're now done. You can run your modified BedlamTicketPrintServer straight from your IDE and use the taskbar icon that appears to print test tickets and receive tickets from the XTS Ticket Server (if the print service isn't running - see [[#Startup - Windows Services]]). When you're happy with your new layout, replace the classes in C:\XTS\PrinterInterface\bin and either restart the Windows Service or just reboot.

==== Changing the Ticket Logo ====

This is much easier than making a new layout. Just replace C:\Xander\ticketlogo.bmp with your new logo. It should have the same dimensions and should probably be just black and white.

XTS

2009-02-21T14:51:50Z

Xander: /* Security */

== eXtensible Ticketing System ==

XTS is the Bedlam Theatre's new ticketing system. It's key feature is extensibility, meaning that if it doesn't do something you want it to do, you (or a suitably inclined geek) should easily be able to add it. Read on for more key features and read further for technical information that will help you maintain and make changes to the system if that is your want.

If you are just looking for help using the software to sell tickets, try [[Using XTS]].

This page is a stub. I intend to document as much of the ticketing system as possible but keep forgetting things that I want to write about. Until it's completed, here's a list of sections that I intend to write under. This article is currently aimed at people who want to maintain the source code, NOT people who want to learn how to sell tickets.

== What I plan to write about ==

* History / Motivation
* Things you should know before you start
** Key Concepts and Terminology
*** "Reserved" vs. "Booked".
*** "Holding" tickets.
*** "Ticket Prototypes"
*** Verifying bookings
*** "Snewts"
*** How XTS handles times between 0AM and 3AM.
** Principles
*** Portability (OS Transparency)
*** Accessibility (Network Transparency)
*** Extensibility
*** Readability
*** Simplicity (Minimum Complexity in the Layers that Matter)
*** High-Level Scripting
* Technologies in use
** HTTP
** XML
** HTML
** CSS
** Python
** Java
** Crypto - Rjindael (AES)
* Parts of the system
** DONE Database
*** DONE Scheduled Database Backup
** DONE Ticket Server
*** DONE Web.py
*** DONE API
** DONE Print Server
*** DONE API
*** DONE Making new ticket layouts
*** DONE Changing the ticket logo
** Static Server
*** Apache 2.2
** Administration Server
** Javascript Client
*** Ami
*** Snewts
*** Prism
** Reporting
*** XSLT
** HTTPProxy
*** Protecting the ticketing server from the proxy
** Startup - Windows Services
*** JSWrapper
* Directory Structure (C:\XTS\)
* Installing XTS
* Making Improvements - A HOWTO
** Known Issues / Things you might like to work on
*** Sniffing attacks
*** No test suite, no TDD
*** Transactions (there aren't any)
*** Printing - it's pretty crap
*** Reports - XSLT, but not as it should be
** Familiarisation
*** Grokking the Source
** Tools You Must Use
*** Firebug
*** IPython
** Things You Must Do
*** DONE Setting up your own dev version from trunk
*** Keeping the documentation up-to-date
** Safe and Unsafe
*** Where is the money?
** Versioning
** Fun Ideas For Improvements or Otherwise
*** Booking from portable devices for producers ("Would you like to come? I'll book you a ticket now.")
*** XTS-controlled DMX for Box Office Lighting Fun Times
*** Heads-up displays for show times and sold out info a-la every cinema you've ever been to

= Documentation =

== Parts of the System ==

=== Database ===

XTS uses a MySQL database. It should be very easy to port XTS to other databases, most access is abstracted through [[#web.py]]'s db module but there may be some report-generating SQL queries that are specific to MySQL in the XTS source. See [[#data.py]] for more info.

The schema is called "xts".

==== Scheduled Database Backups ====

As of 2008-07-18, [[Maude]] is configured to take nightly backups of the XTS database to C:\XTS\Backups. These backups should be scaled back to weeklies or slower at the end of Fringe 2008 or they '''will''' eventually consume all available disk space on the machine. Furthermore the database should occasionally be backed up "off-site" in case of hard disk failure.

=== Ticket Server ===

The ticket server does the hard work of allocating, booking and selling tickets of various types for various performances of various shows. The ticket server is written in [[#Python]]. It is implemented on top of a web server ([http://www.webpy.org web.py]]), allowing clients to interact with the server via [[#HTTP]] using [[#XML]] for data exchange.

The ticket server is accessible via HTTP on port 8080.

==== API ====

API stands for Application Programming Interface. It tells you how you can write programs that talk to the ticket server in order to do useful things (like get show information, or sell tickets online).

The [[#Javascript Client]] uses the XTS API to make a nice box office interface for selling tickets to customers.

If you know a little XML you can write programs that interact with the API yourself. You can write your programs in Java, PHP, Python, Ruby -- whatever. So long as you can make an HTTP connection and deal with a little XML, you're good to go.

See [[XTS API]] for further information and full documentation.

==== Security ====

The ticket server uses host and password authentication to decide who can do what using the API. Full details are in the [[XTS API|API documentation]].

XTS also has a built-in secure proxy (security.py, part of [[#XWF]]), based on AES with a preshared key. It allows trusted remote hosts privileged access to the ticketing server over an encrypted connection.

Applications that want to use the secure method of connecting to the server use a special URL (/v1/secure/v1/connect) and then "trade secrets" with the ticketing server in order to prove it's trustworthiness and verify the trustworthiness of the server. It's all very ingenious and you really shouldn't try doing it yourself until you've taken Computer Security (a really good course) or are Bruce Schneier.

To be honest, it's quite voodoo - but it's also crucial when doing anything regarding ticket sales over the internet. So, really, don't mess with it until you quite know what you're doing.

==== Error Handling ====

When the server encounters an error (for instance, a ticket that you are selling has already been sold), internally it throws a SnewtsError exception.

SnewtsErrors are caught by the request dispatcher (snewtsUrlInvocation in server.py) and turned into an XML-formatted error that is sent back to the client.

SnewtsErrors consist of an error number (useful to computers) and an error message (useful to people). Errors are grouped into types. For instance, all errors that start with the number 404 represent a requested thing not being there ("Not Found"). However, 404.1 specifically means that it was a ticket that wasn't found. 404.2 means a performance wasn't found and so on.

This is important when writing software that talk to the ticket server via the [[#API]]. When reading responses from the server the client software can have a default way of handling 404 errors but additionally can have a specific way of handling 404.5 errors.

Where possible, error numbers correspond to the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html HTTP status code definitions]. This is mostly because I'm perverse and think it's funny that when something isn't there you get a 404 error. However, it can be useful when writing your client software in that a 4xx error indicates that the client probably did something wrong whereas 5xx errors indicate that something went wrong on the server (which is potentially much more serious).

==== XWF ====

XWF is a python module of useful bits of code for writing web applications. The thinking is that only XTS code should be in the XTS module. So if there's some code which does something more generic - like writing log files or providing security - this code should be written in a different module where it doesn't clutter up the code that actually matters.

At time of writing, XWF includes xml.py, which is a lightweight set of functions for very quickly writing XML documents, and security.py, which provides a security layer for remote hosts that need trust and secrecy when talking to the Ticket Server (see [[#Security]]).

==== Source ====

Alphabetically:

===== constants.py =====

Contains various useful constants used in the rest of the XTS source. This makes the code more readable. In the database, the number 2 represents a ticket that is booked. However, instead of using the number 2 to refer to such tickets in the source code, we use the expression <code>ticketstates['BOOKED']</code>. This makes the code (a lot) more readable.

Funnily enough, it's generally a bad idea to change the constants. However, you should add to them where appropriate, for instance, if you intend to record new kinds of events in the log.

''There is nothing technically '''constant''' about the variables in constants.py - they could easily be modified at runtime. If you know how to define constants that are actually constant, or just of a better general approach, then this might be an area of the server that you could improve.''
--[[User:Xander|Xander]] 17:21, 18 July 2008 (BST)

===== data.py =====

data.py provides an interface to the database. Wherever XTS needs to get information from the database, it does it by calling a function in data.py. data.py then takes care of turning the information request into SQL, and if necessary, post-processing the response into a useful form for the caller.

You should be able to port XTS to another datastore simply by replacing data.py and stats.py.

===== exceptions.py =====

exceptions.py defines the SnewtsError exception type. For more information, see [[#Error_Handling]].

===== helpers.py =====

helpers.py contains various functions that help to solve common and recurring problems in the Snewts application (for instance, turning datetime objects into human-readable date strings). This unclutters [[#logic.py]], which should just contain the business logic of how to sell tickets properly. Functions in helpers.py should ideally be moved into [[#XWF]], but who really cares?

===== logic.py =====

logic.py sits between the client request and the database. When the client asks to sell a ticket, logic.py makes sure that the show actually exists, the ticket is valid for the performance, there are enough tickets left and anything else that needs making sure of. If any one bit of XTS is going to get something critically wrong, it's going to be in logic.py.

logic.py never talks to the database directly. To get data from the database and make changes to the database it must call functions in [[#data.py]].

===== printer.py =====

printer.py is an abstraction layer with one synchronous public function, printTicket(). It takes care of sending the ticket to the [[#Print Server]] and making sure that the printer got the ticket. If the print can't be confirmed it throws a SnewtsError.

===== reflection.py =====

reflection.py is a silly bit of code with some functions for counting lines in code. It's used to provide some of the statistics you get when you look at the XTS "about" page, such as how many TODO comments are still left in the code.

reflection.py should be refactored into the XWF module - none of the code is specific to XTS itself, so it shouldn't be cluttering up the snewts module.

===== report.py =====

report.py contains all of the code that formats statistics gathered from the database into XML reports. It also does a little math. See [[#Reporting]].

===== snewts.py =====

snewts.py does the job of recognising requests from clients, checking that the clients are authorised to make the requests, and sending back responses. Simple requests (ie. getPerformances) are fulfilled by getting data from [[#data.py]] directly. More complicated requests are fulfilled by calling business logic in [[#logic.py]] or getting [[#report.py]] to generate reports.

===== stats.py =====

stats.py contains code for calculating various metrics and statistics with regards to the XTS database (such as "how many tickets have been sold?" and "of all of the seats that have been available for all of the shows ever, what percentage of them did we actually sell?"). stats.py accesses the database directly, because otherwise all of the code in stats.py would have to be in data.py, and that would make data.py even bigger than it already is.

===== status.py =====

status.py contains definitions of all of the errors that XTS may reply with when something goes wrong. If you're writing client software, you need to anticipate these coming back at you.

=== Print Server ===

The print server is a separate entity from the ticketing server that handles ticket printing. It listens on the network for messages instructing it to print tickets.

It is written in pure Java for the convenience of Java's layout and printing library. It uses the effective users' default printer for printing (so this printer needs to be set to the ticket printer).

==== API ====

The print server listens for tickets to print on port . Tickets are sent to the printer as UDP messages on port 8301. The UDP message format consists of six strings terminated by the NULL character. It does not support UTF8 encoding. It is very fail. The strings are, in order:

* Show Name
* Date (expected format: ddd YYYY-MM-DD)
* Time (expected format: HH:MM)
* Booking name (can be an empty string)
* Ticket serial
* Ticket type (ie. "Student")

When the print server receives your ticket and succeeds in dispatching it to the printer it will reply with a UDP packet containing the ticket serial you specified.

==== Making new ticket layouts ====

You need to know Java to write new ticket layouts.

Make a pair of new classes implementing uk.org.opentheatre.xts.Ticket and uk.org.opentheatre.xts.TicketFactory. The former must lay out the ticket, the latter must create instances of the ticket. Look at existing ticket classes for examples on how to do this.

Then, modify the uk.co.bedlamtheatre.BedlamTicketPrintServer to use your new TicketFactory class. You're now done. You can run your modified BedlamTicketPrintServer straight from your IDE and use the taskbar icon that appears to print test tickets and receive tickets from the XTS Ticket Server (if the print service isn't running - see [[#Startup - Windows Services]]). When you're happy with your new layout, replace the classes in C:\XTS\PrinterInterface\bin and either restart the Windows Service or just reboot.

==== Changing the Ticket Logo ====

This is much easier than making a new layout. Just replace C:\Xander\ticketlogo.bmp with your new logo. It should have the same dimensions and should probably be just black and white.

== Making Improvements - a HOWTO ==

=== Getting Started ===

==== Setting Up a Development Server ====

These are the steps I needed to take (and didn't need to take, but that you will need to on other platforms) to set up a development server on a new MacBook on 2008-08-27.

You need to be familiar with Terminal, and you'll be using the sudo command to do things as root. If these things sound frightening you should start by googling around a little.

* Install '''XCode Tools'''. You're going to need XCode so that you can build the Python/MySQL adapter and the PyCrypto library later. You can download XCode from http://developer.apple.com/tools/xcode/. It's free, but it's a big download. While you're downloading it, move onto the next couple of steps.

* '''Python 2.5''' is already installed on Mac OS X 10.5. Rejoice.

* '''easy_install''' is already installed on Mac OS X 10.5. Aren't you glad you bought a Mac?

* Install a '''MySQL database server'''. It's free and open-source. http://dev.mysql.com

* '''Add the MySQL server binaries to your path'''. To do this you need to create a bash profile.
$ emacs ~/.bash_profile
Then, put this in the new file you've just created in EMACS:
export PATH=$PATH:/usr/local/mysql/bin
Then save and close your new profile by pressing CTRL-X, CTRL-S, CTRL-X, CTRL-C. Then to make use of your new profile, close and re-open your terminal.

* So long as the previous step went well you should now be able to '''start up your MySQL server''' by typing:
$ sudo safe_mysqld
If that fails to work, you didn't manage to reconfigure your path properly. Google for help.

* Install '''web.py'''
$ sudo easy_install web.py

* Install '''Python Crypto'''
$ sudo easy_install pycrypto
Installing PyCrypto under Windows is not so trivial. You will need to install MinGW, then perform the install manually (or tweak the easy_install configuration). [http://jintoreedwine.wordpress.com/2008/07/20/python-25-and-encryption-pycrypto-under-windows/ This page summarises how to get the job done quickly].

* In order to run the administration interface, install '''Django'''. http://www.djangoproject.com/download/

* Build a '''Python/MySQL adapter'''. Download the tarball from http://sourceforge.net/projects/mysql-python. Then untar it, patch _mysql.c by hand and install. Sounds hard? It is. Hopefully by the time you come to do this, installing the mysql adapter will be as easy as sudo easy_install mysql_python. See http://forums.mysql.com/read.php?50,175059,219216#msg-219216 for more info.
$ tar -xvf MySQL-python-1.2.2.tar
$ cd MySQL-python-1.2.2
$ emacs _mysql.c (... and patch as shown on teh internets -- you need to comment out lines 37-39)
$ sudo python setup.py install
$ sudo mkdir /usr/local/mysql/lib/mysql
$ sudo cp /usr/local/mysql/lib/libmysqlclient_r.15.dylib /usr/local/mysql/lib/mysql/libmysqlclient_r.15.dylib

Hilariously, on Windows, this step is much easier. Just get the binary installer from Sourceforge: http://sourceforge.net/projects/mysql-python

You've now finished installing all of the required software. Next you need to set up the initial data and permissions in the database.

* Download '''CocoaMySQL''', or an alternative MySQL client of your choosing.

* '''Log into your own MySQL server''' as root.

* '''Create a database''' called "xts".

* '''Import a database backup''' from Maude. It's the fastest way to get up and running with plenty of real-world data.

* '''Set permissions''' so that the anonymous user on localhost ("@localhost") has full access to the xts database. These are very lax permissions, but they'll do for a development server.

* Finally, '''run the XTS server'''. In whatever directory you have a copy of the XTS source, run:
$ python server.py
You can now visit http://localhost:8080 in a web browser on your own computer to play around. So long as the version signature under the XTS logo shows "DEV", you're looking at your own server.

* Get hacking.

XTS

2008-10-24T11:38:41Z

Xander: /* Setting Up a Development Server */ Too much sudo

== eXtensible Ticketing System ==

XTS is the Bedlam Theatre's new ticketing system. It's key feature is extensibility, meaning that if it doesn't do something you want it to do, you (or a suitably inclined geek) should easily be able to add it. Read on for more key features and read further for technical information that will help you maintain and make changes to the system if that is your want.

If you are just looking for help using the software to sell tickets, try [[Using XTS]].

This page is a stub. I intend to document as much of the ticketing system as possible but keep forgetting things that I want to write about. Until it's completed, here's a list of sections that I intend to write under. This article is currently aimed at people who want to maintain the source code, NOT people who want to learn how to sell tickets.

== What I plan to write about ==

* History / Motivation
* Things you should know before you start
** Key Concepts and Terminology
*** "Reserved" vs. "Booked".
*** "Holding" tickets.
*** "Ticket Prototypes"
*** Verifying bookings
*** "Snewts"
*** How XTS handles times between 0AM and 3AM.
** Principles
*** Portability (OS Transparency)
*** Accessibility (Network Transparency)
*** Extensibility
*** Readability
*** Simplicity (Minimum Complexity in the Layers that Matter)
*** High-Level Scripting
* Technologies in use
** HTTP
** XML
** HTML
** CSS
** Python
** Java
** Crypto - Rjindael (AES)
* Parts of the system
** DONE Database
*** DONE Scheduled Database Backup
** DONE Ticket Server
*** DONE Web.py
*** DONE API
** DONE Print Server
*** DONE API
*** DONE Making new ticket layouts
*** DONE Changing the ticket logo
** Static Server
*** Apache 2.2
** Administration Server
** Javascript Client
*** Ami
*** Snewts
*** Prism
** Reporting
*** XSLT
** HTTPProxy
*** Protecting the ticketing server from the proxy
** Startup - Windows Services
*** JSWrapper
* Directory Structure (C:\XTS\)
* Installing XTS
* Making Improvements - A HOWTO
** Known Issues / Things you might like to work on
*** Sniffing attacks
*** No test suite, no TDD
*** Transactions (there aren't any)
*** Printing - it's pretty crap
*** Reports - XSLT, but not as it should be
** Familiarisation
*** Grokking the Source
** Tools You Must Use
*** Firebug
*** IPython
** Things You Must Do
*** DONE Setting up your own dev version from trunk
*** Keeping the documentation up-to-date
** Safe and Unsafe
*** Where is the money?
** Versioning
** Fun Ideas For Improvements or Otherwise
*** Booking from portable devices for producers ("Would you like to come? I'll book you a ticket now.")
*** XTS-controlled DMX for Box Office Lighting Fun Times
*** Heads-up displays for show times and sold out info a-la every cinema you've ever been to

= Documentation =

== Parts of the System ==

=== Database ===

XTS uses a MySQL database. It should be very easy to port XTS to other databases, most access is abstracted through [[#web.py]]'s db module but there may be some report-generating SQL queries that are specific to MySQL in the XTS source. See [[#data.py]] for more info.

The schema is called "xts".

==== Scheduled Database Backups ====

As of 2008-07-18, [[Maude]] is configured to take nightly backups of the XTS database to C:\XTS\Backups. These backups should be scaled back to weeklies or slower at the end of Fringe 2008 or they '''will''' eventually consume all available disk space on the machine. Furthermore the database should occasionally be backed up "off-site" in case of hard disk failure.

=== Ticket Server ===

The ticket server does the hard work of allocating, booking and selling tickets of various types for various performances of various shows. The ticket server is written in [[#Python]]. It is implemented on top of a web server ([http://www.webpy.org web.py]]), allowing clients to interact with the server via [[#HTTP]] using [[#XML]] for data exchange.

The ticket server is accessible via HTTP on port 8080.

==== API ====

API stands for Application Programming Interface. It tells you how you can write programs that talk to the ticket server in order to do useful things (like get show information, or sell tickets online).

The [[#Javascript Client]] uses the XTS API to make a nice box office interface for selling tickets to customers.

If you know a little XML you can write programs that interact with the API yourself. You can write your programs in Java, PHP, Python, Ruby -- whatever. So long as you can make an HTTP connection and deal with a little XML, you're good to go.

See [[XTS API]] for further information and full documentation.

==== Security ====

The ticket server uses host and password authentication to decide who can do what using the API. Full details are in the [[XTS API|API documentation]].

XTS also has a built-in secure proxy (security.py, part of [[#XWF]]), based on AES with a preshared key. It allows trusted remote hosts privileged access to the ticketing server over an encrypted connection.

Applications that want to use the secure method of connecting to the server use a special URL (/v1/secure/v1/connect) and then "trade secrets" with the ticketing server in order to prove it's trustworthiness and verify the trustworthiness of the server. It's all very ingenious and you really shouldn't try doing it yourself until you've taken Computer Security (a really good course) or are Bruce Sterling.

To be honest, it's quite voodoo - but it's also crucial when doing anything regarding ticket sales over the internet. So, really, don't mess with it until you quite know what you're doing.

==== Error Handling ====

When the server encounters an error (for instance, a ticket that you are selling has already been sold), internally it throws a SnewtsError exception.

SnewtsErrors are caught by the request dispatcher (snewtsUrlInvocation in server.py) and turned into an XML-formatted error that is sent back to the client.

SnewtsErrors consist of an error number (useful to computers) and an error message (useful to people). Errors are grouped into types. For instance, all errors that start with the number 404 represent a requested thing not being there ("Not Found"). However, 404.1 specifically means that it was a ticket that wasn't found. 404.2 means a performance wasn't found and so on.

This is important when writing software that talk to the ticket server via the [[#API]]. When reading responses from the server the client software can have a default way of handling 404 errors but additionally can have a specific way of handling 404.5 errors.

Where possible, error numbers correspond to the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html HTTP status code definitions]. This is mostly because I'm perverse and think it's funny that when something isn't there you get a 404 error. However, it can be useful when writing your client software in that a 4xx error indicates that the client probably did something wrong whereas 5xx errors indicate that something went wrong on the server (which is potentially much more serious).

==== XWF ====

XWF is a python module of useful bits of code for writing web applications. The thinking is that only XTS code should be in the XTS module. So if there's some code which does something more generic - like writing log files or providing security - this code should be written in a different module where it doesn't clutter up the code that actually matters.

At time of writing, XWF includes xml.py, which is a lightweight set of functions for very quickly writing XML documents, and security.py, which provides a security layer for remote hosts that need trust and secrecy when talking to the Ticket Server (see [[#Security]]).

==== Source ====

Alphabetically:

===== constants.py =====

Contains various useful constants used in the rest of the XTS source. This makes the code more readable. In the database, the number 2 represents a ticket that is booked. However, instead of using the number 2 to refer to such tickets in the source code, we use the expression <code>ticketstates['BOOKED']</code>. This makes the code (a lot) more readable.

Funnily enough, it's generally a bad idea to change the constants. However, you should add to them where appropriate, for instance, if you intend to record new kinds of events in the log.

''There is nothing technically '''constant''' about the variables in constants.py - they could easily be modified at runtime. If you know how to define constants that are actually constant, or just of a better general approach, then this might be an area of the server that you could improve.''
--[[User:Xander|Xander]] 17:21, 18 July 2008 (BST)

===== data.py =====

data.py provides an interface to the database. Wherever XTS needs to get information from the database, it does it by calling a function in data.py. data.py then takes care of turning the information request into SQL, and if necessary, post-processing the response into a useful form for the caller.

You should be able to port XTS to another datastore simply by replacing data.py and stats.py.

===== exceptions.py =====

exceptions.py defines the SnewtsError exception type. For more information, see [[#Error_Handling]].

===== helpers.py =====

helpers.py contains various functions that help to solve common and recurring problems in the Snewts application (for instance, turning datetime objects into human-readable date strings). This unclutters [[#logic.py]], which should just contain the business logic of how to sell tickets properly. Functions in helpers.py should ideally be moved into [[#XWF]], but who really cares?

===== logic.py =====

logic.py sits between the client request and the database. When the client asks to sell a ticket, logic.py makes sure that the show actually exists, the ticket is valid for the performance, there are enough tickets left and anything else that needs making sure of. If any one bit of XTS is going to get something critically wrong, it's going to be in logic.py.

logic.py never talks to the database directly. To get data from the database and make changes to the database it must call functions in [[#data.py]].

===== printer.py =====

printer.py is an abstraction layer with one synchronous public function, printTicket(). It takes care of sending the ticket to the [[#Print Server]] and making sure that the printer got the ticket. If the print can't be confirmed it throws a SnewtsError.

===== reflection.py =====

reflection.py is a silly bit of code with some functions for counting lines in code. It's used to provide some of the statistics you get when you look at the XTS "about" page, such as how many TODO comments are still left in the code.

reflection.py should be refactored into the XWF module - none of the code is specific to XTS itself, so it shouldn't be cluttering up the snewts module.

===== report.py =====

report.py contains all of the code that formats statistics gathered from the database into XML reports. It also does a little math. See [[#Reporting]].

===== snewts.py =====

snewts.py does the job of recognising requests from clients, checking that the clients are authorised to make the requests, and sending back responses. Simple requests (ie. getPerformances) are fulfilled by getting data from [[#data.py]] directly. More complicated requests are fulfilled by calling business logic in [[#logic.py]] or getting [[#report.py]] to generate reports.

===== stats.py =====

stats.py contains code for calculating various metrics and statistics with regards to the XTS database (such as "how many tickets have been sold?" and "of all of the seats that have been available for all of the shows ever, what percentage of them did we actually sell?"). stats.py accesses the database directly, because otherwise all of the code in stats.py would have to be in data.py, and that would make data.py even bigger than it already is.

===== status.py =====

status.py contains definitions of all of the errors that XTS may reply with when something goes wrong. If you're writing client software, you need to anticipate these coming back at you.

=== Print Server ===

The print server is a separate entity from the ticketing server that handles ticket printing. It listens on the network for messages instructing it to print tickets.

It is written in pure Java for the convenience of Java's layout and printing library. It uses the effective users' default printer for printing (so this printer needs to be set to the ticket printer).

==== API ====

The print server listens for tickets to print on port . Tickets are sent to the printer as UDP messages on port 8301. The UDP message format consists of six strings terminated by the NULL character. It does not support UTF8 encoding. It is very fail. The strings are, in order:

* Show Name
* Date (expected format: ddd YYYY-MM-DD)
* Time (expected format: HH:MM)
* Booking name (can be an empty string)
* Ticket serial
* Ticket type (ie. "Student")

When the print server receives your ticket and succeeds in dispatching it to the printer it will reply with a UDP packet containing the ticket serial you specified.

==== Making new ticket layouts ====

You need to know Java to write new ticket layouts.

Make a pair of new classes implementing uk.org.opentheatre.xts.Ticket and uk.org.opentheatre.xts.TicketFactory. The former must lay out the ticket, the latter must create instances of the ticket. Look at existing ticket classes for examples on how to do this.

Then, modify the uk.co.bedlamtheatre.BedlamTicketPrintServer to use your new TicketFactory class. You're now done. You can run your modified BedlamTicketPrintServer straight from your IDE and use the taskbar icon that appears to print test tickets and receive tickets from the XTS Ticket Server (if the print service isn't running - see [[#Startup - Windows Services]]). When you're happy with your new layout, replace the classes in C:\XTS\PrinterInterface\bin and either restart the Windows Service or just reboot.

==== Changing the Ticket Logo ====

This is much easier than making a new layout. Just replace C:\Xander\ticketlogo.bmp with your new logo. It should have the same dimensions and should probably be just black and white.

== Making Improvements - a HOWTO ==

=== Getting Started ===

==== Setting Up a Development Server ====

These are the steps I needed to take (and didn't need to take, but that you will need to on other platforms) to set up a development server on a new MacBook on 2008-08-27.

You need to be familiar with Terminal, and you'll be using the sudo command to do things as root. If these things sound frightening you should start by googling around a little.

* Install '''XCode Tools'''. You're going to need XCode so that you can build the Python/MySQL adapter and the PyCrypto library later. You can download XCode from http://developer.apple.com/tools/xcode/. It's free, but it's a big download. While you're downloading it, move onto the next couple of steps.

* '''Python 2.5''' is already installed on Mac OS X 10.5. Rejoice.

* '''easy_install''' is already installed on Mac OS X 10.5. Aren't you glad you bought a Mac?

* Install a '''MySQL database server'''. It's free and open-source. http://dev.mysql.com

* '''Add the MySQL server binaries to your path'''. To do this you need to create a bash profile.
$ emacs ~/.bash_profile
Then, put this in the new file you've just created in EMACS:
export PATH=$PATH:/usr/local/mysql/bin
Then save and close your new profile by pressing CTRL-X, CTRL-S, CTRL-X, CTRL-C. Then to make use of your new profile, close and re-open your terminal.

* So long as the previous step went well you should now be able to '''start up your MySQL server''' by typing:
$ sudo safe_mysqld
If that fails to work, you didn't manage to reconfigure your path properly. Google for help.

* Install '''web.py'''
$ sudo easy_install web.py

* Install '''Python Crypto'''
$ sudo easy_install pycrypto
Installing PyCrypto under Windows is not so trivial. You will need to install MinGW, then perform the install manually (or tweak the easy_install configuration). [http://jintoreedwine.wordpress.com/2008/07/20/python-25-and-encryption-pycrypto-under-windows/ This page summarises how to get the job done quickly].

* In order to run the administration interface, install '''Django'''. http://www.djangoproject.com/download/

* Build a '''Python/MySQL adapter'''. Download the tarball from http://sourceforge.net/projects/mysql-python. Then untar it, patch _mysql.c by hand and install. Sounds hard? It is. Hopefully by the time you come to do this, installing the mysql adapter will be as easy as sudo easy_install mysql_python. See http://forums.mysql.com/read.php?50,175059,219216#msg-219216 for more info.
$ tar -xvf MySQL-python-1.2.2.tar
$ cd MySQL-python-1.2.2
$ emacs _mysql.c (... and patch as shown on teh internets -- you need to comment out lines 37-39)
$ sudo python setup.py install
$ sudo mkdir /usr/local/mysql/lib/mysql
$ sudo cp /usr/local/mysql/lib/libmysqlclient_r.15.dylib /usr/local/mysql/lib/mysql/libmysqlclient_r.15.dylib

Hilariously, on Windows, this step is much easier. Just get the binary installer from Sourceforge: http://sourceforge.net/projects/mysql-python

You've now finished installing all of the required software. Next you need to set up the initial data and permissions in the database.

* Download '''CocoaMySQL''', or an alternative MySQL client of your choosing.

* '''Log into your own MySQL server''' as root.

* '''Create a database''' called "xts".

* '''Import a database backup''' from Maude. It's the fastest way to get up and running with plenty of real-world data.

* '''Set permissions''' so that the anonymous user on localhost ("@localhost") has full access to the xts database. These are very lax permissions, but they'll do for a development server.

* Finally, '''run the XTS server'''. In whatever directory you have a copy of the XTS source, run:
$ python server.py
You can now visit http://localhost:8080 in a web browser on your own computer to play around. So long as the version signature under the XTS logo shows "DEV", you're looking at your own server.

* Get hacking.

XTS

2008-10-16T06:23:23Z

Xander: /* Setting Up a Development Server */

== eXtensible Ticketing System ==

XTS is the Bedlam Theatre's new ticketing system. It's key feature is extensibility, meaning that if it doesn't do something you want it to do, you (or a suitably inclined geek) should easily be able to add it. Read on for more key features and read further for technical information that will help you maintain and make changes to the system if that is your want.

If you are just looking for help using the software to sell tickets, try [[Using XTS]].

This page is a stub. I intend to document as much of the ticketing system as possible but keep forgetting things that I want to write about. Until it's completed, here's a list of sections that I intend to write under. This article is currently aimed at people who want to maintain the source code, NOT people who want to learn how to sell tickets.

== What I plan to write about ==

* History / Motivation
* Things you should know before you start
** Key Concepts and Terminology
*** "Reserved" vs. "Booked".
*** "Holding" tickets.
*** "Ticket Prototypes"
*** Verifying bookings
*** "Snewts"
*** How XTS handles times between 0AM and 3AM.
** Principles
*** Portability (OS Transparency)
*** Accessibility (Network Transparency)
*** Extensibility
*** Readability
*** Simplicity (Minimum Complexity in the Layers that Matter)
*** High-Level Scripting
* Technologies in use
** HTTP
** XML
** HTML
** CSS
** Python
** Java
** Crypto - Rjindael (AES)
* Parts of the system
** DONE Database
*** DONE Scheduled Database Backup
** DONE Ticket Server
*** DONE Web.py
*** DONE API
** DONE Print Server
*** DONE API
*** DONE Making new ticket layouts
*** DONE Changing the ticket logo
** Static Server
*** Apache 2.2
** Administration Server
** Javascript Client
*** Ami
*** Snewts
*** Prism
** Reporting
*** XSLT
** HTTPProxy
*** Protecting the ticketing server from the proxy
** Startup - Windows Services
*** JSWrapper
* Directory Structure (C:\XTS\)
* Installing XTS
* Making Improvements - A HOWTO
** Known Issues / Things you might like to work on
*** Sniffing attacks
*** No test suite, no TDD
*** Transactions (there aren't any)
*** Printing - it's pretty crap
*** Reports - XSLT, but not as it should be
** Familiarisation
*** Grokking the Source
** Tools You Must Use
*** Firebug
*** IPython
** Things You Must Do
*** DONE Setting up your own dev version from trunk
*** Keeping the documentation up-to-date
** Safe and Unsafe
*** Where is the money?
** Versioning
** Fun Ideas For Improvements or Otherwise
*** Booking from portable devices for producers ("Would you like to come? I'll book you a ticket now.")
*** XTS-controlled DMX for Box Office Lighting Fun Times
*** Heads-up displays for show times and sold out info a-la every cinema you've ever been to

= Documentation =

== Parts of the System ==

=== Database ===

XTS uses a MySQL database. It should be very easy to port XTS to other databases, most access is abstracted through [[#web.py]]'s db module but there may be some report-generating SQL queries that are specific to MySQL in the XTS source. See [[#data.py]] for more info.

The schema is called "xts".

==== Scheduled Database Backups ====

As of 2008-07-18, [[Maude]] is configured to take nightly backups of the XTS database to C:\XTS\Backups. These backups should be scaled back to weeklies or slower at the end of Fringe 2008 or they '''will''' eventually consume all available disk space on the machine. Furthermore the database should occasionally be backed up "off-site" in case of hard disk failure.

=== Ticket Server ===

The ticket server does the hard work of allocating, booking and selling tickets of various types for various performances of various shows. The ticket server is written in [[#Python]]. It is implemented on top of a web server ([http://www.webpy.org web.py]]), allowing clients to interact with the server via [[#HTTP]] using [[#XML]] for data exchange.

The ticket server is accessible via HTTP on port 8080.

==== API ====

API stands for Application Programming Interface. It tells you how you can write programs that talk to the ticket server in order to do useful things (like get show information, or sell tickets online).

The [[#Javascript Client]] uses the XTS API to make a nice box office interface for selling tickets to customers.

If you know a little XML you can write programs that interact with the API yourself. You can write your programs in Java, PHP, Python, Ruby -- whatever. So long as you can make an HTTP connection and deal with a little XML, you're good to go.

See [[XTS API]] for further information and full documentation.

==== Security ====

The ticket server uses host and password authentication to decide who can do what using the API. Full details are in the [[XTS API|API documentation]].

XTS also has a built-in secure proxy (security.py, part of [[#XWF]]), based on AES with a preshared key. It allows trusted remote hosts privileged access to the ticketing server over an encrypted connection.

Applications that want to use the secure method of connecting to the server use a special URL (/v1/secure/v1/connect) and then "trade secrets" with the ticketing server in order to prove it's trustworthiness and verify the trustworthiness of the server. It's all very ingenious and you really shouldn't try doing it yourself until you've taken Computer Security (a really good course) or are Bruce Sterling.

To be honest, it's quite voodoo - but it's also crucial when doing anything regarding ticket sales over the internet. So, really, don't mess with it until you quite know what you're doing.

==== Error Handling ====

When the server encounters an error (for instance, a ticket that you are selling has already been sold), internally it throws a SnewtsError exception.

SnewtsErrors are caught by the request dispatcher (snewtsUrlInvocation in server.py) and turned into an XML-formatted error that is sent back to the client.

SnewtsErrors consist of an error number (useful to computers) and an error message (useful to people). Errors are grouped into types. For instance, all errors that start with the number 404 represent a requested thing not being there ("Not Found"). However, 404.1 specifically means that it was a ticket that wasn't found. 404.2 means a performance wasn't found and so on.

This is important when writing software that talk to the ticket server via the [[#API]]. When reading responses from the server the client software can have a default way of handling 404 errors but additionally can have a specific way of handling 404.5 errors.

Where possible, error numbers correspond to the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html HTTP status code definitions]. This is mostly because I'm perverse and think it's funny that when something isn't there you get a 404 error. However, it can be useful when writing your client software in that a 4xx error indicates that the client probably did something wrong whereas 5xx errors indicate that something went wrong on the server (which is potentially much more serious).

==== XWF ====

XWF is a python module of useful bits of code for writing web applications. The thinking is that only XTS code should be in the XTS module. So if there's some code which does something more generic - like writing log files or providing security - this code should be written in a different module where it doesn't clutter up the code that actually matters.

At time of writing, XWF includes xml.py, which is a lightweight set of functions for very quickly writing XML documents, and security.py, which provides a security layer for remote hosts that need trust and secrecy when talking to the Ticket Server (see [[#Security]]).

==== Source ====

Alphabetically:

===== constants.py =====

Contains various useful constants used in the rest of the XTS source. This makes the code more readable. In the database, the number 2 represents a ticket that is booked. However, instead of using the number 2 to refer to such tickets in the source code, we use the expression <code>ticketstates['BOOKED']</code>. This makes the code (a lot) more readable.

Funnily enough, it's generally a bad idea to change the constants. However, you should add to them where appropriate, for instance, if you intend to record new kinds of events in the log.

''There is nothing technically '''constant''' about the variables in constants.py - they could easily be modified at runtime. If you know how to define constants that are actually constant, or just of a better general approach, then this might be an area of the server that you could improve.''
--[[User:Xander|Xander]] 17:21, 18 July 2008 (BST)

===== data.py =====

data.py provides an interface to the database. Wherever XTS needs to get information from the database, it does it by calling a function in data.py. data.py then takes care of turning the information request into SQL, and if necessary, post-processing the response into a useful form for the caller.

You should be able to port XTS to another datastore simply by replacing data.py and stats.py.

===== exceptions.py =====

exceptions.py defines the SnewtsError exception type. For more information, see [[#Error_Handling]].

===== helpers.py =====

helpers.py contains various functions that help to solve common and recurring problems in the Snewts application (for instance, turning datetime objects into human-readable date strings). This unclutters [[#logic.py]], which should just contain the business logic of how to sell tickets properly. Functions in helpers.py should ideally be moved into [[#XWF]], but who really cares?

===== logic.py =====

logic.py sits between the client request and the database. When the client asks to sell a ticket, logic.py makes sure that the show actually exists, the ticket is valid for the performance, there are enough tickets left and anything else that needs making sure of. If any one bit of XTS is going to get something critically wrong, it's going to be in logic.py.

logic.py never talks to the database directly. To get data from the database and make changes to the database it must call functions in [[#data.py]].

===== printer.py =====

printer.py is an abstraction layer with one synchronous public function, printTicket(). It takes care of sending the ticket to the [[#Print Server]] and making sure that the printer got the ticket. If the print can't be confirmed it throws a SnewtsError.

===== reflection.py =====

reflection.py is a silly bit of code with some functions for counting lines in code. It's used to provide some of the statistics you get when you look at the XTS "about" page, such as how many TODO comments are still left in the code.

reflection.py should be refactored into the XWF module - none of the code is specific to XTS itself, so it shouldn't be cluttering up the snewts module.

===== report.py =====

report.py contains all of the code that formats statistics gathered from the database into XML reports. It also does a little math. See [[#Reporting]].

===== snewts.py =====

snewts.py does the job of recognising requests from clients, checking that the clients are authorised to make the requests, and sending back responses. Simple requests (ie. getPerformances) are fulfilled by getting data from [[#data.py]] directly. More complicated requests are fulfilled by calling business logic in [[#logic.py]] or getting [[#report.py]] to generate reports.

===== stats.py =====

stats.py contains code for calculating various metrics and statistics with regards to the XTS database (such as "how many tickets have been sold?" and "of all of the seats that have been available for all of the shows ever, what percentage of them did we actually sell?"). stats.py accesses the database directly, because otherwise all of the code in stats.py would have to be in data.py, and that would make data.py even bigger than it already is.

===== status.py =====

status.py contains definitions of all of the errors that XTS may reply with when something goes wrong. If you're writing client software, you need to anticipate these coming back at you.

=== Print Server ===

The print server is a separate entity from the ticketing server that handles ticket printing. It listens on the network for messages instructing it to print tickets.

It is written in pure Java for the convenience of Java's layout and printing library. It uses the effective users' default printer for printing (so this printer needs to be set to the ticket printer).

==== API ====

The print server listens for tickets to print on port . Tickets are sent to the printer as UDP messages on port 8301. The UDP message format consists of six strings terminated by the NULL character. It does not support UTF8 encoding. It is very fail. The strings are, in order:

* Show Name
* Date (expected format: ddd YYYY-MM-DD)
* Time (expected format: HH:MM)
* Booking name (can be an empty string)
* Ticket serial
* Ticket type (ie. "Student")

When the print server receives your ticket and succeeds in dispatching it to the printer it will reply with a UDP packet containing the ticket serial you specified.

==== Making new ticket layouts ====

You need to know Java to write new ticket layouts.

Make a pair of new classes implementing uk.org.opentheatre.xts.Ticket and uk.org.opentheatre.xts.TicketFactory. The former must lay out the ticket, the latter must create instances of the ticket. Look at existing ticket classes for examples on how to do this.

Then, modify the uk.co.bedlamtheatre.BedlamTicketPrintServer to use your new TicketFactory class. You're now done. You can run your modified BedlamTicketPrintServer straight from your IDE and use the taskbar icon that appears to print test tickets and receive tickets from the XTS Ticket Server (if the print service isn't running - see [[#Startup - Windows Services]]). When you're happy with your new layout, replace the classes in C:\XTS\PrinterInterface\bin and either restart the Windows Service or just reboot.

==== Changing the Ticket Logo ====

This is much easier than making a new layout. Just replace C:\Xander\ticketlogo.bmp with your new logo. It should have the same dimensions and should probably be just black and white.

== Making Improvements - a HOWTO ==

=== Getting Started ===

==== Setting Up a Development Server ====

These are the steps I needed to take (and didn't need to take, but that you will need to on other platforms) to set up a development server on a new MacBook on 2008-08-27.

You need to be familiar with Terminal, and you'll be using the sudo command to do things as root. If these things sound frightening you should start by googling around a little.

* Install '''XCode Tools'''. You're going to need XCode so that you can build the Python/MySQL adapter and the PyCrypto library later. You can download XCode from http://developer.apple.com/tools/xcode/. It's free, but it's a big download. While you're downloading it, move onto the next couple of steps.

* '''Python 2.5''' is already installed on Mac OS X 10.5. Rejoice.

* '''easy_install''' is already installed on Mac OS X 10.5. Aren't you glad you bought a Mac?

* Install a '''MySQL database server'''. It's free and open-source. http://dev.mysql.com

* '''Add the MySQL server binaries to your path'''. To do this you need to create a bash profile.
$ sudo emacs ~/.bash_profile
Then, put this in the new file you've just created in EMACS:
export PATH=$PATH:/usr/local/mysql/bin
Then save and close your new profile by pressing CTRL-X, CTRL-S, CTRL-X, CTRL-C. Then to make use of your new profile, close and re-open your terminal.

* So long as the previous step went well you should now be able to '''start up your MySQL server''' by typing:
$ sudo safe_mysqld
If that fails to work, you didn't manage to reconfigure your path properly. Google for help.

* Install '''web.py'''
$ sudo easy_install web.py

* Install '''Python Crypto'''
$ sudo easy_install pycrypto
Installing PyCrypto under Windows is not so trivial. You will need to install MinGW, then perform the install manually (or tweak the easy_install configuration). [http://jintoreedwine.wordpress.com/2008/07/20/python-25-and-encryption-pycrypto-under-windows/ This page summarises how to get the job done quickly].

* In order to run the administration interface, install '''Django'''. http://www.djangoproject.com/download/

* Build a '''Python/MySQL adapter'''. Download the tarball from http://sourceforge.net/projects/mysql-python. Then untar it, patch _mysql.c by hand and install. Sounds hard? It is. Hopefully by the time you come to do this, installing the mysql adapter will be as easy as sudo easy_install mysql_python. See http://forums.mysql.com/read.php?50,175059,219216#msg-219216 for more info.
$ tar -xvf MySQL-python-1.2.2.tar
$ cd MySQL-python-1.2.2
$ emacs _mysql.c (... and patch as shown on teh internets -- you need to comment out lines 37-39)
$ sudo python setup.py install
$ sudo mkdir /usr/local/mysql/lib/mysql
$ sudo cp /usr/local/mysql/lib/libmysqlclient_r.15.dylib /usr/local/mysql/lib/mysql/libmysqlclient_r.15.dylib

Hilariously, on Windows, this step is much easier. Just get the binary installer from Sourceforge: http://sourceforge.net/projects/mysql-python

You've now finished installing all of the required software. Next you need to set up the initial data and permissions in the database.

* Download '''CocoaMySQL''', or an alternative MySQL client of your choosing.

* '''Log into your own MySQL server''' as root.

* '''Create a database''' called "xts".

* '''Import a database backup''' from Maude. It's the fastest way to get up and running with plenty of real-world data.

* '''Set permissions''' so that the anonymous user on localhost ("@localhost") has full access to the xts database. These are very lax permissions, but they'll do for a development server.

* Finally, '''run the XTS server'''. In whatever directory you have a copy of the XTS source, run:
$ python server.py
You can now visit http://localhost:8080 in a web browser on your own computer to play around. So long as the version signature under the XTS logo shows "DEV", you're looking at your own server.

* Get hacking.

XTS

2008-10-16T06:22:49Z

Xander: /* Ticket Server */ Various updates.

== eXtensible Ticketing System ==

XTS is the Bedlam Theatre's new ticketing system. It's key feature is extensibility, meaning that if it doesn't do something you want it to do, you (or a suitably inclined geek) should easily be able to add it. Read on for more key features and read further for technical information that will help you maintain and make changes to the system if that is your want.

If you are just looking for help using the software to sell tickets, try [[Using XTS]].

This page is a stub. I intend to document as much of the ticketing system as possible but keep forgetting things that I want to write about. Until it's completed, here's a list of sections that I intend to write under. This article is currently aimed at people who want to maintain the source code, NOT people who want to learn how to sell tickets.

== What I plan to write about ==

* History / Motivation
* Things you should know before you start
** Key Concepts and Terminology
*** "Reserved" vs. "Booked".
*** "Holding" tickets.
*** "Ticket Prototypes"
*** Verifying bookings
*** "Snewts"
*** How XTS handles times between 0AM and 3AM.
** Principles
*** Portability (OS Transparency)
*** Accessibility (Network Transparency)
*** Extensibility
*** Readability
*** Simplicity (Minimum Complexity in the Layers that Matter)
*** High-Level Scripting
* Technologies in use
** HTTP
** XML
** HTML
** CSS
** Python
** Java
** Crypto - Rjindael (AES)
* Parts of the system
** DONE Database
*** DONE Scheduled Database Backup
** DONE Ticket Server
*** DONE Web.py
*** DONE API
** DONE Print Server
*** DONE API
*** DONE Making new ticket layouts
*** DONE Changing the ticket logo
** Static Server
*** Apache 2.2
** Administration Server
** Javascript Client
*** Ami
*** Snewts
*** Prism
** Reporting
*** XSLT
** HTTPProxy
*** Protecting the ticketing server from the proxy
** Startup - Windows Services
*** JSWrapper
* Directory Structure (C:\XTS\)
* Installing XTS
* Making Improvements - A HOWTO
** Known Issues / Things you might like to work on
*** Sniffing attacks
*** No test suite, no TDD
*** Transactions (there aren't any)
*** Printing - it's pretty crap
*** Reports - XSLT, but not as it should be
** Familiarisation
*** Grokking the Source
** Tools You Must Use
*** Firebug
*** IPython
** Things You Must Do
*** DONE Setting up your own dev version from trunk
*** Keeping the documentation up-to-date
** Safe and Unsafe
*** Where is the money?
** Versioning
** Fun Ideas For Improvements or Otherwise
*** Booking from portable devices for producers ("Would you like to come? I'll book you a ticket now.")
*** XTS-controlled DMX for Box Office Lighting Fun Times
*** Heads-up displays for show times and sold out info a-la every cinema you've ever been to

= Documentation =

== Parts of the System ==

=== Database ===

XTS uses a MySQL database. It should be very easy to port XTS to other databases, most access is abstracted through [[#web.py]]'s db module but there may be some report-generating SQL queries that are specific to MySQL in the XTS source. See [[#data.py]] for more info.

The schema is called "xts".

==== Scheduled Database Backups ====

As of 2008-07-18, [[Maude]] is configured to take nightly backups of the XTS database to C:\XTS\Backups. These backups should be scaled back to weeklies or slower at the end of Fringe 2008 or they '''will''' eventually consume all available disk space on the machine. Furthermore the database should occasionally be backed up "off-site" in case of hard disk failure.

=== Ticket Server ===

The ticket server does the hard work of allocating, booking and selling tickets of various types for various performances of various shows. The ticket server is written in [[#Python]]. It is implemented on top of a web server ([http://www.webpy.org web.py]]), allowing clients to interact with the server via [[#HTTP]] using [[#XML]] for data exchange.

The ticket server is accessible via HTTP on port 8080.

==== API ====

API stands for Application Programming Interface. It tells you how you can write programs that talk to the ticket server in order to do useful things (like get show information, or sell tickets online).

The [[#Javascript Client]] uses the XTS API to make a nice box office interface for selling tickets to customers.

If you know a little XML you can write programs that interact with the API yourself. You can write your programs in Java, PHP, Python, Ruby -- whatever. So long as you can make an HTTP connection and deal with a little XML, you're good to go.

See [[XTS API]] for further information and full documentation.

==== Security ====

The ticket server uses host and password authentication to decide who can do what using the API. Full details are in the [[XTS API|API documentation]].

XTS also has a built-in secure proxy (security.py, part of [[#XWF]]), based on AES with a preshared key. It allows trusted remote hosts privileged access to the ticketing server over an encrypted connection.

Applications that want to use the secure method of connecting to the server use a special URL (/v1/secure/v1/connect) and then "trade secrets" with the ticketing server in order to prove it's trustworthiness and verify the trustworthiness of the server. It's all very ingenious and you really shouldn't try doing it yourself until you've taken Computer Security (a really good course) or are Bruce Sterling.

To be honest, it's quite voodoo - but it's also crucial when doing anything regarding ticket sales over the internet. So, really, don't mess with it until you quite know what you're doing.

==== Error Handling ====

When the server encounters an error (for instance, a ticket that you are selling has already been sold), internally it throws a SnewtsError exception.

SnewtsErrors are caught by the request dispatcher (snewtsUrlInvocation in server.py) and turned into an XML-formatted error that is sent back to the client.

SnewtsErrors consist of an error number (useful to computers) and an error message (useful to people). Errors are grouped into types. For instance, all errors that start with the number 404 represent a requested thing not being there ("Not Found"). However, 404.1 specifically means that it was a ticket that wasn't found. 404.2 means a performance wasn't found and so on.

This is important when writing software that talk to the ticket server via the [[#API]]. When reading responses from the server the client software can have a default way of handling 404 errors but additionally can have a specific way of handling 404.5 errors.

Where possible, error numbers correspond to the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html HTTP status code definitions]. This is mostly because I'm perverse and think it's funny that when something isn't there you get a 404 error. However, it can be useful when writing your client software in that a 4xx error indicates that the client probably did something wrong whereas 5xx errors indicate that something went wrong on the server (which is potentially much more serious).

==== XWF ====

XWF is a python module of useful bits of code for writing web applications. The thinking is that only XTS code should be in the XTS module. So if there's some code which does something more generic - like writing log files or providing security - this code should be written in a different module where it doesn't clutter up the code that actually matters.

At time of writing, XWF includes xml.py, which is a lightweight set of functions for very quickly writing XML documents, and security.py, which provides a security layer for remote hosts that need trust and secrecy when talking to the Ticket Server (see [[#Security]]).

==== Source ====

Alphabetically:

===== constants.py =====

Contains various useful constants used in the rest of the XTS source. This makes the code more readable. In the database, the number 2 represents a ticket that is booked. However, instead of using the number 2 to refer to such tickets in the source code, we use the expression <code>ticketstates['BOOKED']</code>. This makes the code (a lot) more readable.

Funnily enough, it's generally a bad idea to change the constants. However, you should add to them where appropriate, for instance, if you intend to record new kinds of events in the log.

''There is nothing technically '''constant''' about the variables in constants.py - they could easily be modified at runtime. If you know how to define constants that are actually constant, or just of a better general approach, then this might be an area of the server that you could improve.''
--[[User:Xander|Xander]] 17:21, 18 July 2008 (BST)

===== data.py =====

data.py provides an interface to the database. Wherever XTS needs to get information from the database, it does it by calling a function in data.py. data.py then takes care of turning the information request into SQL, and if necessary, post-processing the response into a useful form for the caller.

You should be able to port XTS to another datastore simply by replacing data.py and stats.py.

===== exceptions.py =====

exceptions.py defines the SnewtsError exception type. For more information, see [[#Error_Handling]].

===== helpers.py =====

helpers.py contains various functions that help to solve common and recurring problems in the Snewts application (for instance, turning datetime objects into human-readable date strings). This unclutters [[#logic.py]], which should just contain the business logic of how to sell tickets properly. Functions in helpers.py should ideally be moved into [[#XWF]], but who really cares?

===== logic.py =====

logic.py sits between the client request and the database. When the client asks to sell a ticket, logic.py makes sure that the show actually exists, the ticket is valid for the performance, there are enough tickets left and anything else that needs making sure of. If any one bit of XTS is going to get something critically wrong, it's going to be in logic.py.

logic.py never talks to the database directly. To get data from the database and make changes to the database it must call functions in [[#data.py]].

===== printer.py =====

printer.py is an abstraction layer with one synchronous public function, printTicket(). It takes care of sending the ticket to the [[#Print Server]] and making sure that the printer got the ticket. If the print can't be confirmed it throws a SnewtsError.

===== reflection.py =====

reflection.py is a silly bit of code with some functions for counting lines in code. It's used to provide some of the statistics you get when you look at the XTS "about" page, such as how many TODO comments are still left in the code.

reflection.py should be refactored into the XWF module - none of the code is specific to XTS itself, so it shouldn't be cluttering up the snewts module.

===== report.py =====

report.py contains all of the code that formats statistics gathered from the database into XML reports. It also does a little math. See [[#Reporting]].

===== snewts.py =====

snewts.py does the job of recognising requests from clients, checking that the clients are authorised to make the requests, and sending back responses. Simple requests (ie. getPerformances) are fulfilled by getting data from [[#data.py]] directly. More complicated requests are fulfilled by calling business logic in [[#logic.py]] or getting [[#report.py]] to generate reports.

===== stats.py =====

stats.py contains code for calculating various metrics and statistics with regards to the XTS database (such as "how many tickets have been sold?" and "of all of the seats that have been available for all of the shows ever, what percentage of them did we actually sell?"). stats.py accesses the database directly, because otherwise all of the code in stats.py would have to be in data.py, and that would make data.py even bigger than it already is.

===== status.py =====

status.py contains definitions of all of the errors that XTS may reply with when something goes wrong. If you're writing client software, you need to anticipate these coming back at you.

=== Print Server ===

The print server is a separate entity from the ticketing server that handles ticket printing. It listens on the network for messages instructing it to print tickets.

It is written in pure Java for the convenience of Java's layout and printing library. It uses the effective users' default printer for printing (so this printer needs to be set to the ticket printer).

==== API ====

The print server listens for tickets to print on port . Tickets are sent to the printer as UDP messages on port 8301. The UDP message format consists of six strings terminated by the NULL character. It does not support UTF8 encoding. It is very fail. The strings are, in order:

* Show Name
* Date (expected format: ddd YYYY-MM-DD)
* Time (expected format: HH:MM)
* Booking name (can be an empty string)
* Ticket serial
* Ticket type (ie. "Student")

When the print server receives your ticket and succeeds in dispatching it to the printer it will reply with a UDP packet containing the ticket serial you specified.

==== Making new ticket layouts ====

You need to know Java to write new ticket layouts.

Make a pair of new classes implementing uk.org.opentheatre.xts.Ticket and uk.org.opentheatre.xts.TicketFactory. The former must lay out the ticket, the latter must create instances of the ticket. Look at existing ticket classes for examples on how to do this.

Then, modify the uk.co.bedlamtheatre.BedlamTicketPrintServer to use your new TicketFactory class. You're now done. You can run your modified BedlamTicketPrintServer straight from your IDE and use the taskbar icon that appears to print test tickets and receive tickets from the XTS Ticket Server (if the print service isn't running - see [[#Startup - Windows Services]]). When you're happy with your new layout, replace the classes in C:\XTS\PrinterInterface\bin and either restart the Windows Service or just reboot.

==== Changing the Ticket Logo ====

This is much easier than making a new layout. Just replace C:\Xander\ticketlogo.bmp with your new logo. It should have the same dimensions and should probably be just black and white.

== Making Improvements - a HOWTO ==

=== Getting Started ===

==== Setting Up a Development Server ====

These are the steps I needed to take (and didn't need to take, but that you will need to on other platforms) to set up a development server on a new MacBook on 2008-08-27.

You need to be familiar with Terminal, and you'll be using the sudo command to do things as root. If these things sound frightening you should start by googling around a little.

* Install '''XCode Tools'''. You're going to need XCode so that you can build the Python/MySQL adapter and the PyCrypto library later. You can download XCode from http://developer.apple.com/tools/xcode/. It's free, but it's a big download. While you're downloading it, move onto the next couple of steps.

* '''Python 2.5''' is already installed on Mac OS X 10.5. Rejoice.

* '''easy_install''' is already installed on Mac OS X 10.5. Aren't you glad you bought a Mac?

* Install a '''MySQL database server'''. It's free and open-source. http://dev.mysql.com

* '''Add the MySQL server binaries to your path'''. To do this you need to create a bash profile.
$ sudo emacs ~/.bash_profile
Then, put this in the new file you've just created in EMACS:
export PATH=$PATH:/usr/local/mysql/bin
Then save and close your new profile by pressing CTRL-X, CTRL-S, CTRL-X, CTRL-C. Then to make use of your new profile, close and re-open your terminal.

* So long as the previous step went well you should now be able to '''start up your MySQL server''' by typing:
$ sudo safe_mysqld
If that fails to work, you didn't manage to reconfigure your path properly. Google for help.

* Install '''web.py'''
$ sudo easy_install web.py

* Install "Python Crypto"
$ sudo easy_install pycrypto
Installing PyCrypto under Windows is not so trivial. You will need to install MinGW, then perform the install manually (or tweak the easy_install configuration). [http://jintoreedwine.wordpress.com/2008/07/20/python-25-and-encryption-pycrypto-under-windows/ This page summarises how to get the job done quickly].

* In order to run the administration interface, install '''Django'''. http://www.djangoproject.com/download/

* Build a '''Python/MySQL adapter'''. Download the tarball from http://sourceforge.net/projects/mysql-python. Then untar it, patch _mysql.c by hand and install. Sounds hard? It is. Hopefully by the time you come to do this, installing the mysql adapter will be as easy as sudo easy_install mysql_python. See http://forums.mysql.com/read.php?50,175059,219216#msg-219216 for more info.
$ tar -xvf MySQL-python-1.2.2.tar
$ cd MySQL-python-1.2.2
$ emacs _mysql.c (... and patch as shown on teh internets -- you need to comment out lines 37-39)
$ sudo python setup.py install
$ sudo mkdir /usr/local/mysql/lib/mysql
$ sudo cp /usr/local/mysql/lib/libmysqlclient_r.15.dylib /usr/local/mysql/lib/mysql/libmysqlclient_r.15.dylib

Hilariously, on Windows, this step is much easier. Just get the binary installer from Sourceforge: http://sourceforge.net/projects/mysql-python

You've now finished installing all of the required software. Next you need to set up the initial data and permissions in the database.

* Download '''CocoaMySQL''', or an alternative MySQL client of your choosing.

* '''Log into your own MySQL server''' as root.

* '''Create a database''' called "xts".

* '''Import a database backup''' from Maude. It's the fastest way to get up and running with plenty of real-world data.

* '''Set permissions''' so that the anonymous user on localhost ("@localhost") has full access to the xts database. These are very lax permissions, but they'll do for a development server.

* Finally, '''run the XTS server'''. In whatever directory you have a copy of the XTS source, run:
$ python server.py
You can now visit http://localhost:8080 in a web browser on your own computer to play around. So long as the version signature under the XTS logo shows "DEV", you're looking at your own server.

* Get hacking.

XTS

2008-10-16T06:01:57Z

Xander: /* Setting Up a Development Server */ Additions regarding new crypto library.

== eXtensible Ticketing System ==

XTS is the Bedlam Theatre's new ticketing system. It's key feature is extensibility, meaning that if it doesn't do something you want it to do, you (or a suitably inclined geek) should easily be able to add it. Read on for more key features and read further for technical information that will help you maintain and make changes to the system if that is your want.

If you are just looking for help using the software to sell tickets, try [[Using XTS]].

This page is a stub. I intend to document as much of the ticketing system as possible but keep forgetting things that I want to write about. Until it's completed, here's a list of sections that I intend to write under. This article is currently aimed at people who want to maintain the source code, NOT people who want to learn how to sell tickets.

== What I plan to write about ==

* History / Motivation
* Things you should know before you start
** Key Concepts and Terminology
*** "Reserved" vs. "Booked".
*** "Holding" tickets.
*** "Ticket Prototypes"
*** Verifying bookings
*** "Snewts"
*** How XTS handles times between 0AM and 3AM.
** Principles
*** Portability (OS Transparency)
*** Accessibility (Network Transparency)
*** Extensibility
*** Readability
*** Simplicity (Minimum Complexity in the Layers that Matter)
*** High-Level Scripting
* Technologies in use
** HTTP
** XML
** HTML
** CSS
** Python
** Java
** Crypto - Rjindael (AES)
* Parts of the system
** DONE Database
*** DONE Scheduled Database Backup
** DONE Ticket Server
*** DONE Web.py
*** DONE API
** DONE Print Server
*** DONE API
*** DONE Making new ticket layouts
*** DONE Changing the ticket logo
** Static Server
*** Apache 2.2
** Administration Server
** Javascript Client
*** Ami
*** Snewts
*** Prism
** Reporting
*** XSLT
** HTTPProxy
*** Protecting the ticketing server from the proxy
** Startup - Windows Services
*** JSWrapper
* Directory Structure (C:\XTS\)
* Installing XTS
* Making Improvements - A HOWTO
** Known Issues / Things you might like to work on
*** Sniffing attacks
*** No test suite, no TDD
*** Transactions (there aren't any)
*** Printing - it's pretty crap
*** Reports - XSLT, but not as it should be
** Familiarisation
*** Grokking the Source
** Tools You Must Use
*** Firebug
*** IPython
** Things You Must Do
*** DONE Setting up your own dev version from trunk
*** Keeping the documentation up-to-date
** Safe and Unsafe
*** Where is the money?
** Versioning
** Fun Ideas For Improvements or Otherwise
*** Booking from portable devices for producers ("Would you like to come? I'll book you a ticket now.")
*** XTS-controlled DMX for Box Office Lighting Fun Times
*** Heads-up displays for show times and sold out info a-la every cinema you've ever been to

= Documentation =

== Parts of the System ==

=== Database ===

XTS uses a MySQL database. It should be very easy to port XTS to other databases, most access is abstracted through [[#web.py]]'s db module but there may be some report-generating SQL queries that are specific to MySQL in the XTS source. See [[#data.py]] for more info.

The schema is called "xts".

==== Scheduled Database Backups ====

As of 2008-07-18, [[Maude]] is configured to take nightly backups of the XTS database to C:\XTS\Backups. These backups should be scaled back to weeklies or slower at the end of Fringe 2008 or they '''will''' eventually consume all available disk space on the machine. Furthermore the database should occasionally be backed up "off-site" in case of hard disk failure.

=== Ticket Server ===

The ticket server does the hard work of allocating, booking and selling tickets of various types for various performances of various shows. The ticket server is written in [[#Python]]. It is implemented on top of a web server ([http://www.webpy.org web.py]]), allowing clients to interact with the server via [[#HTTP]] using [[#XML]] for data exchange.

The ticket server is accessible via HTTP on port 8080.

==== API ====

API stands for Application Programming Interface. It tells you how you can write programs that talk to the ticket server in order to do useful things (like get show information, or sell tickets online).

The [[#Javascript Client]] uses the XTS API to make a nice box office interface for selling tickets to customers.

If you know a little XML and HTTP you can write programs that interact with the API yourself.

See [[XTS API]] for further information and full documentation.

==== Security ====

The ticket server uses host and password authentication to decide who can do what using the API. Full details are in the [[XTS API|API documentation]].

==== Error Handling ====

When the server encounters an error (for instance, a ticket that you are selling has already been sold), internally it throws a SnewtsError exception.

SnewtsErrors are caught by the request dispatcher (snewtsUrlInvocation in server.py) and turned into an XML-formatted error that is sent back to the client.

SnewtsErrors consist of an error number (useful to computers) and an error message (useful to people). Errors are grouped into types. For instance, all errors that start with the number 404 represent a requested thing not being there ("Not Found"). However, 404.1 specifically means that it was a ticket that wasn't found. 404.2 means a performance wasn't found and so on.

This is important when writing software that talk to the ticket server via the [[#API]]. When reading responses from the server the client software can have a default way of handling 404 errors but additionally can have a specific way of handling 404.5 errors.

Where possible, error numbers correspond to the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html HTTP status code definitions]. This is mostly because I'm perverse and think it's funny that when something isn't there you get a 404 error. However, it can be useful when writing your client software in that a 4xx error indicates that the client probably did something wrong whereas 5xx errors indicate that something went wrong on the server (which is potentially much more serious).

==== Source ====

Alphabetically:

===== constants.py =====

Contains various useful constants used in the rest of the XTS source. This makes the code more readable. In the database, the number 2 represents a ticket that is booked. However, instead of using the number 2 to refer to such tickets in the source code, we use the expression <code>ticketstates['BOOKED']</code>. This makes the code (a lot) more readable.

Funnily enough, it's generally a bad idea to change the constants. However, you should add to them where appropriate, for instance, if you intend to record new kinds of events in the log.

''There is nothing technically '''constant''' about the variables in constants.py - they could easily be modified at runtime. If you know how to define constants that are actually constant, or just of a better general approach, then this might be an area of the server that you could improve.''
--[[User:Xander|Xander]] 17:21, 18 July 2008 (BST)

===== data.py =====

data.py provides an interface to the database. Wherever XTS needs to get information from the database, it does it by calling a function in data.py. data.py then takes care of turning the information request into SQL, and if necessary, post-processing the response into a useful form for the caller.

You should be able to port XTS to another datastore simply by replacing data.py.

===== exceptions.py =====

exceptions.py defines the SnewtsError exception type. For more information, see [[#Error_Handling]].

===== helpers.py =====

helpers.py contains various functions that help to solve common and recurring problems in the Snewts application (for instance, turning datetime objects into human-readable date strings). This unclutters [[#logic.py]], which should just contain the business logic of how to sell tickets properly. Functions in helpers.py should ideally be moved into [[#XWF]], but who really cares?

===== logic.py =====

logic.py sits between the client request and the database. When the client asks to sell a ticket, logic.py makes sure that the show actually exists, the ticket is valid for the performance, there are enough tickets left and anything else that needs making sure of. If any one bit of XTS is going to get something critically wrong, it's going to be in logic.py.

logic.py never talks to the database directly. To get data from the database and make changes to the database it must call functions in [[#data.py]].

===== printer.py =====

printer.py is an abstraction layer with one synchronous public function, printTicket(). It takes care of sending the ticket to the [[#Print Server]] and making sure that the printer got the ticket. If the print can't be confirmed it throws a SnewtsError.

===== report.py =====

report.py contains all of the code that formats statistics gathered from the database into XML reports. It also does a little math. See [[#Reporting]].

===== snewts.py =====

snewts.py does the job of recognising requests from clients, checking that the clients are authorised to make the requests, and sending back responses. Simple requests (ie. getPerformances) are fulfilled by getting data from [[#data.py]] directly. More complicated requests are fulfilled by calling business logic in [[#logic.py]] or getting [[#report.py]] to generate reports.

===== status.py =====

status.py contains definitions of all of the errors that XTS may reply with when something goes wrong. If you're writing client software, you need to anticipate these coming back at you.

=== Print Server ===

The print server is a separate entity from the ticketing server that handles ticket printing. It listens on the network for messages instructing it to print tickets.

It is written in pure Java for the convenience of Java's layout and printing library. It uses the effective users' default printer for printing (so this printer needs to be set to the ticket printer).

==== API ====

The print server listens for tickets to print on port . Tickets are sent to the printer as UDP messages on port 8301. The UDP message format consists of six strings terminated by the NULL character. It does not support UTF8 encoding. It is very fail. The strings are, in order:

* Show Name
* Date (expected format: ddd YYYY-MM-DD)
* Time (expected format: HH:MM)
* Booking name (can be an empty string)
* Ticket serial
* Ticket type (ie. "Student")

When the print server receives your ticket and succeeds in dispatching it to the printer it will reply with a UDP packet containing the ticket serial you specified.

==== Making new ticket layouts ====

You need to know Java to write new ticket layouts.

Make a pair of new classes implementing uk.org.opentheatre.xts.Ticket and uk.org.opentheatre.xts.TicketFactory. The former must lay out the ticket, the latter must create instances of the ticket. Look at existing ticket classes for examples on how to do this.

Then, modify the uk.co.bedlamtheatre.BedlamTicketPrintServer to use your new TicketFactory class. You're now done. You can run your modified BedlamTicketPrintServer straight from your IDE and use the taskbar icon that appears to print test tickets and receive tickets from the XTS Ticket Server (if the print service isn't running - see [[#Startup - Windows Services]]). When you're happy with your new layout, replace the classes in C:\XTS\PrinterInterface\bin and either restart the Windows Service or just reboot.

==== Changing the Ticket Logo ====

This is much easier than making a new layout. Just replace C:\Xander\ticketlogo.bmp with your new logo. It should have the same dimensions and should probably be just black and white.

== Making Improvements - a HOWTO ==

=== Getting Started ===

==== Setting Up a Development Server ====

These are the steps I needed to take (and didn't need to take, but that you will need to on other platforms) to set up a development server on a new MacBook on 2008-08-27.

You need to be familiar with Terminal, and you'll be using the sudo command to do things as root. If these things sound frightening you should start by googling around a little.

* Install '''XCode Tools'''. You're going to need XCode so that you can build the Python/MySQL adapter and the PyCrypto library later. You can download XCode from http://developer.apple.com/tools/xcode/. It's free, but it's a big download. While you're downloading it, move onto the next couple of steps.

* '''Python 2.5''' is already installed on Mac OS X 10.5. Rejoice.

* '''easy_install''' is already installed on Mac OS X 10.5. Aren't you glad you bought a Mac?

* Install a '''MySQL database server'''. It's free and open-source. http://dev.mysql.com

* '''Add the MySQL server binaries to your path'''. To do this you need to create a bash profile.
$ sudo emacs ~/.bash_profile
Then, put this in the new file you've just created in EMACS:
export PATH=$PATH:/usr/local/mysql/bin
Then save and close your new profile by pressing CTRL-X, CTRL-S, CTRL-X, CTRL-C. Then to make use of your new profile, close and re-open your terminal.

* So long as the previous step went well you should now be able to '''start up your MySQL server''' by typing:
$ sudo safe_mysqld
If that fails to work, you didn't manage to reconfigure your path properly. Google for help.

* Install '''web.py'''
$ sudo easy_install web.py

* Install "Python Crypto"
$ sudo easy_install pycrypto
Installing PyCrypto under Windows is not so trivial. You will need to install MinGW, then perform the install manually (or tweak the easy_install configuration). [http://jintoreedwine.wordpress.com/2008/07/20/python-25-and-encryption-pycrypto-under-windows/ This page summarises how to get the job done quickly].

* In order to run the administration interface, install '''Django'''. http://www.djangoproject.com/download/

* Build a '''Python/MySQL adapter'''. Download the tarball from http://sourceforge.net/projects/mysql-python. Then untar it, patch _mysql.c by hand and install. Sounds hard? It is. Hopefully by the time you come to do this, installing the mysql adapter will be as easy as sudo easy_install mysql_python. See http://forums.mysql.com/read.php?50,175059,219216#msg-219216 for more info.
$ tar -xvf MySQL-python-1.2.2.tar
$ cd MySQL-python-1.2.2
$ emacs _mysql.c (... and patch as shown on teh internets -- you need to comment out lines 37-39)
$ sudo python setup.py install
$ sudo mkdir /usr/local/mysql/lib/mysql
$ sudo cp /usr/local/mysql/lib/libmysqlclient_r.15.dylib /usr/local/mysql/lib/mysql/libmysqlclient_r.15.dylib

Hilariously, on Windows, this step is much easier. Just get the binary installer from Sourceforge: http://sourceforge.net/projects/mysql-python

You've now finished installing all of the required software. Next you need to set up the initial data and permissions in the database.

* Download '''CocoaMySQL''', or an alternative MySQL client of your choosing.

* '''Log into your own MySQL server''' as root.

* '''Create a database''' called "xts".

* '''Import a database backup''' from Maude. It's the fastest way to get up and running with plenty of real-world data.

* '''Set permissions''' so that the anonymous user on localhost ("@localhost") has full access to the xts database. These are very lax permissions, but they'll do for a development server.

* Finally, '''run the XTS server'''. In whatever directory you have a copy of the XTS source, run:
$ python server.py
You can now visit http://localhost:8080 in a web browser on your own computer to play around. So long as the version signature under the XTS logo shows "DEV", you're looking at your own server.

* Get hacking.

XTS

2008-10-15T14:06:01Z

Xander: /* Getting Started */ Pycrypto

== eXtensible Ticketing System ==

XTS is the Bedlam Theatre's new ticketing system. It's key feature is extensibility, meaning that if it doesn't do something you want it to do, you (or a suitably inclined geek) should easily be able to add it. Read on for more key features and read further for technical information that will help you maintain and make changes to the system if that is your want.

If you are just looking for help using the software to sell tickets, try [[Using XTS]].

This page is a stub. I intend to document as much of the ticketing system as possible but keep forgetting things that I want to write about. Until it's completed, here's a list of sections that I intend to write under. This article is currently aimed at people who want to maintain the source code, NOT people who want to learn how to sell tickets.

== What I plan to write about ==

* History / Motivation
* Things you should know before you start
** Key Concepts and Terminology
*** "Reserved" vs. "Booked".
*** "Holding" tickets.
*** "Ticket Prototypes"
*** Verifying bookings
*** "Snewts"
*** How XTS handles times between 0AM and 3AM.
** Principles
*** Portability (OS Transparency)
*** Accessibility (Network Transparency)
*** Extensibility
*** Readability
*** Simplicity (Minimum Complexity in the Layers that Matter)
*** High-Level Scripting
* Technologies in use
** HTTP
** XML
** HTML
** CSS
** Python
** Java
** Crypto - Rjindael (AES)
* Parts of the system
** DONE Database
*** DONE Scheduled Database Backup
** DONE Ticket Server
*** DONE Web.py
*** DONE API
** DONE Print Server
*** DONE API
*** DONE Making new ticket layouts
*** DONE Changing the ticket logo
** Static Server
*** Apache 2.2
** Administration Server
** Javascript Client
*** Ami
*** Snewts
*** Prism
** Reporting
*** XSLT
** HTTPProxy
*** Protecting the ticketing server from the proxy
** Startup - Windows Services
*** JSWrapper
* Directory Structure (C:\XTS\)
* Installing XTS
* Making Improvements - A HOWTO
** Known Issues / Things you might like to work on
*** Sniffing attacks
*** No test suite, no TDD
*** Transactions (there aren't any)
*** Printing - it's pretty crap
*** Reports - XSLT, but not as it should be
** Familiarisation
*** Grokking the Source
** Tools You Must Use
*** Firebug
*** IPython
** Things You Must Do
*** DONE Setting up your own dev version from trunk
*** Keeping the documentation up-to-date
** Safe and Unsafe
*** Where is the money?
** Versioning
** Fun Ideas For Improvements or Otherwise
*** Booking from portable devices for producers ("Would you like to come? I'll book you a ticket now.")
*** XTS-controlled DMX for Box Office Lighting Fun Times
*** Heads-up displays for show times and sold out info a-la every cinema you've ever been to

= Documentation =

== Parts of the System ==

=== Database ===

XTS uses a MySQL database. It should be very easy to port XTS to other databases, most access is abstracted through [[#web.py]]'s db module but there may be some report-generating SQL queries that are specific to MySQL in the XTS source. See [[#data.py]] for more info.

The schema is called "xts".

==== Scheduled Database Backups ====

As of 2008-07-18, [[Maude]] is configured to take nightly backups of the XTS database to C:\XTS\Backups. These backups should be scaled back to weeklies or slower at the end of Fringe 2008 or they '''will''' eventually consume all available disk space on the machine. Furthermore the database should occasionally be backed up "off-site" in case of hard disk failure.

=== Ticket Server ===

The ticket server does the hard work of allocating, booking and selling tickets of various types for various performances of various shows. The ticket server is written in [[#Python]]. It is implemented on top of a web server ([http://www.webpy.org web.py]]), allowing clients to interact with the server via [[#HTTP]] using [[#XML]] for data exchange.

The ticket server is accessible via HTTP on port 8080.

==== API ====

API stands for Application Programming Interface. It tells you how you can write programs that talk to the ticket server in order to do useful things (like get show information, or sell tickets online).

The [[#Javascript Client]] uses the XTS API to make a nice box office interface for selling tickets to customers.

If you know a little XML and HTTP you can write programs that interact with the API yourself.

See [[XTS API]] for further information and full documentation.

==== Security ====

The ticket server uses host and password authentication to decide who can do what using the API. Full details are in the [[XTS API|API documentation]].

==== Error Handling ====

When the server encounters an error (for instance, a ticket that you are selling has already been sold), internally it throws a SnewtsError exception.

SnewtsErrors are caught by the request dispatcher (snewtsUrlInvocation in server.py) and turned into an XML-formatted error that is sent back to the client.

SnewtsErrors consist of an error number (useful to computers) and an error message (useful to people). Errors are grouped into types. For instance, all errors that start with the number 404 represent a requested thing not being there ("Not Found"). However, 404.1 specifically means that it was a ticket that wasn't found. 404.2 means a performance wasn't found and so on.

This is important when writing software that talk to the ticket server via the [[#API]]. When reading responses from the server the client software can have a default way of handling 404 errors but additionally can have a specific way of handling 404.5 errors.

Where possible, error numbers correspond to the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html HTTP status code definitions]. This is mostly because I'm perverse and think it's funny that when something isn't there you get a 404 error. However, it can be useful when writing your client software in that a 4xx error indicates that the client probably did something wrong whereas 5xx errors indicate that something went wrong on the server (which is potentially much more serious).

==== Source ====

Alphabetically:

===== constants.py =====

Contains various useful constants used in the rest of the XTS source. This makes the code more readable. In the database, the number 2 represents a ticket that is booked. However, instead of using the number 2 to refer to such tickets in the source code, we use the expression <code>ticketstates['BOOKED']</code>. This makes the code (a lot) more readable.

Funnily enough, it's generally a bad idea to change the constants. However, you should add to them where appropriate, for instance, if you intend to record new kinds of events in the log.

''There is nothing technically '''constant''' about the variables in constants.py - they could easily be modified at runtime. If you know how to define constants that are actually constant, or just of a better general approach, then this might be an area of the server that you could improve.''
--[[User:Xander|Xander]] 17:21, 18 July 2008 (BST)

===== data.py =====

data.py provides an interface to the database. Wherever XTS needs to get information from the database, it does it by calling a function in data.py. data.py then takes care of turning the information request into SQL, and if necessary, post-processing the response into a useful form for the caller.

You should be able to port XTS to another datastore simply by replacing data.py.

===== exceptions.py =====

exceptions.py defines the SnewtsError exception type. For more information, see [[#Error_Handling]].

===== helpers.py =====

helpers.py contains various functions that help to solve common and recurring problems in the Snewts application (for instance, turning datetime objects into human-readable date strings). This unclutters [[#logic.py]], which should just contain the business logic of how to sell tickets properly. Functions in helpers.py should ideally be moved into [[#XWF]], but who really cares?

===== logic.py =====

logic.py sits between the client request and the database. When the client asks to sell a ticket, logic.py makes sure that the show actually exists, the ticket is valid for the performance, there are enough tickets left and anything else that needs making sure of. If any one bit of XTS is going to get something critically wrong, it's going to be in logic.py.

logic.py never talks to the database directly. To get data from the database and make changes to the database it must call functions in [[#data.py]].

===== printer.py =====

printer.py is an abstraction layer with one synchronous public function, printTicket(). It takes care of sending the ticket to the [[#Print Server]] and making sure that the printer got the ticket. If the print can't be confirmed it throws a SnewtsError.

===== report.py =====

report.py contains all of the code that formats statistics gathered from the database into XML reports. It also does a little math. See [[#Reporting]].

===== snewts.py =====

snewts.py does the job of recognising requests from clients, checking that the clients are authorised to make the requests, and sending back responses. Simple requests (ie. getPerformances) are fulfilled by getting data from [[#data.py]] directly. More complicated requests are fulfilled by calling business logic in [[#logic.py]] or getting [[#report.py]] to generate reports.

===== status.py =====

status.py contains definitions of all of the errors that XTS may reply with when something goes wrong. If you're writing client software, you need to anticipate these coming back at you.

=== Print Server ===

The print server is a separate entity from the ticketing server that handles ticket printing. It listens on the network for messages instructing it to print tickets.

It is written in pure Java for the convenience of Java's layout and printing library. It uses the effective users' default printer for printing (so this printer needs to be set to the ticket printer).

==== API ====

The print server listens for tickets to print on port . Tickets are sent to the printer as UDP messages on port 8301. The UDP message format consists of six strings terminated by the NULL character. It does not support UTF8 encoding. It is very fail. The strings are, in order:

* Show Name
* Date (expected format: ddd YYYY-MM-DD)
* Time (expected format: HH:MM)
* Booking name (can be an empty string)
* Ticket serial
* Ticket type (ie. "Student")

When the print server receives your ticket and succeeds in dispatching it to the printer it will reply with a UDP packet containing the ticket serial you specified.

==== Making new ticket layouts ====

You need to know Java to write new ticket layouts.

Make a pair of new classes implementing uk.org.opentheatre.xts.Ticket and uk.org.opentheatre.xts.TicketFactory. The former must lay out the ticket, the latter must create instances of the ticket. Look at existing ticket classes for examples on how to do this.

Then, modify the uk.co.bedlamtheatre.BedlamTicketPrintServer to use your new TicketFactory class. You're now done. You can run your modified BedlamTicketPrintServer straight from your IDE and use the taskbar icon that appears to print test tickets and receive tickets from the XTS Ticket Server (if the print service isn't running - see [[#Startup - Windows Services]]). When you're happy with your new layout, replace the classes in C:\XTS\PrinterInterface\bin and either restart the Windows Service or just reboot.

==== Changing the Ticket Logo ====

This is much easier than making a new layout. Just replace C:\Xander\ticketlogo.bmp with your new logo. It should have the same dimensions and should probably be just black and white.

== Making Improvements - a HOWTO ==

=== Getting Started ===

==== Setting Up a Development Server ====

These are the steps I needed to take (and didn't need to take, but that you will need to on other platforms) to set up a development server on a new MacBook on 2008-08-27.

You need to be familiar with Terminal, and you'll be using the sudo command to do things as root. If these things sound frightening you should start by googling around a little.

* Install '''XCode Tools'''. You're going to need XCode so that you can build the Python/MySQL adapter later. You can download XCode from http://developer.apple.com/tools/xcode/. It's free, but it's a big download. While you're downloading it, move onto the next couple of steps.
* '''Python 2.5''' is already installed on Mac OS X 10.5. Rejoice.
* '''easy_install''' is already installed on Mac OS X 10.5. Aren't you glad you bought a Mac?
* Install a '''MySQL database server'''. It's free and open-source. http://dev.mysql.com
* '''Add the MySQL server binaries to your path'''. To do this you need to create a bash profile.
$ sudo emacs .bash_profile
Then, put this in the new file you've just created in EMACS:
export PATH=$PATH:/usr/local/mysql/bin
Then save and close your new profile by pressing CTRL-X, CTRL-S, XTRL-X, CTRL-C. Then to make use of your new profile, close and re-open your terminal.
* So long as the previous step went well you should now be able to '''start up your MySQL server''' by typing:
$ sudo safe_mysqld
If that fails to work, you didn't manage to reconfigure your path properly. Google for help.
* Install '''web.py'''
$ sudo easy_install web.py
* Install "Python Crypto"
$ sudo easy_install pycrypto
This step relates to a part of XTS that is under development at time of writing. Pycrypto is the cryptographic package that I favour at the moment because it doesn't have any external dependencies, and thus *should* be easier to build on Windows. However, as I write, I'm still at least needing to install MinGW in order to have the headers needed for compiling from C. So we'll see. --[[User:Xander|Xander]] 15:06, 15 October 2008 (BST)
* In order to run the administration interface, install '''Django'''. http://www.djangoproject.com/download/
* Build a '''Python/MySQL adapter'''. Download the tarball from http://sourceforge.net/projects/mysql-python. Then untar it, patch _mysql.c by hand and install. Sounds hard? It is. Hopefully by the time you come to do this, installing the mysql adapter will be as easy as sudo easy_install mysql_python. See http://forums.mysql.com/read.php?50,175059,219216#msg-219216 for more info.
$ tar -xvf MySQL-python-1.2.2.tar
$ cd MySQL-python-1.2.2
$ emacs _mysql.c (... and patch as shown on teh internets -- you need to comment out lines 37-39)
$ sudo python setup.py install
$ sudo mkdir /usr/local/mysql/lib/mysql
$ sudo cp /usr/local/mysql/lib/libmysqlclient_r.15.dylib /usr/local/mysql/lib/mysql/libmysqlclient_r.15.dylib
You've now finished installing all of the required software. Next you need to set up the initial data and permissions in the database.
* Download '''CocoaMySQL''', or an alternative MySQL client of your choosing.
* '''Log into your own MySQL server''' as root.
* '''Create a database''' called "xts".
* '''Import a database backup''' from Maude. It's the fastest way to get up and running with plenty of real-world data.
* '''Set permissions''' so that the anonymous user on localhost ("@localhost") has full access to the xts database. These are very lax permissions, but they'll do for a development server.
* Finally, '''run the XTS server'''. In whatever directory you have a copy of the XTS source, run:
$ python server.py
You can now visit http://localhost:8080 in a web browser on your own computer to play around. So long as the version signature under the XTS logo shows "DEV", you're looking at your own server.
* Get hacking.

XTS

2008-10-15T14:03:18Z

Xander: /* What I plan to write about */ XTS now has a crypto layer that needs documentation

== eXtensible Ticketing System ==

XTS is the Bedlam Theatre's new ticketing system. It's key feature is extensibility, meaning that if it doesn't do something you want it to do, you (or a suitably inclined geek) should easily be able to add it. Read on for more key features and read further for technical information that will help you maintain and make changes to the system if that is your want.

If you are just looking for help using the software to sell tickets, try [[Using XTS]].

This page is a stub. I intend to document as much of the ticketing system as possible but keep forgetting things that I want to write about. Until it's completed, here's a list of sections that I intend to write under. This article is currently aimed at people who want to maintain the source code, NOT people who want to learn how to sell tickets.

== What I plan to write about ==

* History / Motivation
* Things you should know before you start
** Key Concepts and Terminology
*** "Reserved" vs. "Booked".
*** "Holding" tickets.
*** "Ticket Prototypes"
*** Verifying bookings
*** "Snewts"
*** How XTS handles times between 0AM and 3AM.
** Principles
*** Portability (OS Transparency)
*** Accessibility (Network Transparency)
*** Extensibility
*** Readability
*** Simplicity (Minimum Complexity in the Layers that Matter)
*** High-Level Scripting
* Technologies in use
** HTTP
** XML
** HTML
** CSS
** Python
** Java
** Crypto - Rjindael (AES)
* Parts of the system
** DONE Database
*** DONE Scheduled Database Backup
** DONE Ticket Server
*** DONE Web.py
*** DONE API
** DONE Print Server
*** DONE API
*** DONE Making new ticket layouts
*** DONE Changing the ticket logo
** Static Server
*** Apache 2.2
** Administration Server
** Javascript Client
*** Ami
*** Snewts
*** Prism
** Reporting
*** XSLT
** HTTPProxy
*** Protecting the ticketing server from the proxy
** Startup - Windows Services
*** JSWrapper
* Directory Structure (C:\XTS\)
* Installing XTS
* Making Improvements - A HOWTO
** Known Issues / Things you might like to work on
*** Sniffing attacks
*** No test suite, no TDD
*** Transactions (there aren't any)
*** Printing - it's pretty crap
*** Reports - XSLT, but not as it should be
** Familiarisation
*** Grokking the Source
** Tools You Must Use
*** Firebug
*** IPython
** Things You Must Do
*** DONE Setting up your own dev version from trunk
*** Keeping the documentation up-to-date
** Safe and Unsafe
*** Where is the money?
** Versioning
** Fun Ideas For Improvements or Otherwise
*** Booking from portable devices for producers ("Would you like to come? I'll book you a ticket now.")
*** XTS-controlled DMX for Box Office Lighting Fun Times
*** Heads-up displays for show times and sold out info a-la every cinema you've ever been to

= Documentation =

== Parts of the System ==

=== Database ===

XTS uses a MySQL database. It should be very easy to port XTS to other databases, most access is abstracted through [[#web.py]]'s db module but there may be some report-generating SQL queries that are specific to MySQL in the XTS source. See [[#data.py]] for more info.

The schema is called "xts".

==== Scheduled Database Backups ====

As of 2008-07-18, [[Maude]] is configured to take nightly backups of the XTS database to C:\XTS\Backups. These backups should be scaled back to weeklies or slower at the end of Fringe 2008 or they '''will''' eventually consume all available disk space on the machine. Furthermore the database should occasionally be backed up "off-site" in case of hard disk failure.

=== Ticket Server ===

The ticket server does the hard work of allocating, booking and selling tickets of various types for various performances of various shows. The ticket server is written in [[#Python]]. It is implemented on top of a web server ([http://www.webpy.org web.py]]), allowing clients to interact with the server via [[#HTTP]] using [[#XML]] for data exchange.

The ticket server is accessible via HTTP on port 8080.

==== API ====

API stands for Application Programming Interface. It tells you how you can write programs that talk to the ticket server in order to do useful things (like get show information, or sell tickets online).

The [[#Javascript Client]] uses the XTS API to make a nice box office interface for selling tickets to customers.

If you know a little XML and HTTP you can write programs that interact with the API yourself.

See [[XTS API]] for further information and full documentation.

==== Security ====

The ticket server uses host and password authentication to decide who can do what using the API. Full details are in the [[XTS API|API documentation]].

==== Error Handling ====

When the server encounters an error (for instance, a ticket that you are selling has already been sold), internally it throws a SnewtsError exception.

SnewtsErrors are caught by the request dispatcher (snewtsUrlInvocation in server.py) and turned into an XML-formatted error that is sent back to the client.

SnewtsErrors consist of an error number (useful to computers) and an error message (useful to people). Errors are grouped into types. For instance, all errors that start with the number 404 represent a requested thing not being there ("Not Found"). However, 404.1 specifically means that it was a ticket that wasn't found. 404.2 means a performance wasn't found and so on.

This is important when writing software that talk to the ticket server via the [[#API]]. When reading responses from the server the client software can have a default way of handling 404 errors but additionally can have a specific way of handling 404.5 errors.

Where possible, error numbers correspond to the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html HTTP status code definitions]. This is mostly because I'm perverse and think it's funny that when something isn't there you get a 404 error. However, it can be useful when writing your client software in that a 4xx error indicates that the client probably did something wrong whereas 5xx errors indicate that something went wrong on the server (which is potentially much more serious).

==== Source ====

Alphabetically:

===== constants.py =====

Contains various useful constants used in the rest of the XTS source. This makes the code more readable. In the database, the number 2 represents a ticket that is booked. However, instead of using the number 2 to refer to such tickets in the source code, we use the expression <code>ticketstates['BOOKED']</code>. This makes the code (a lot) more readable.

Funnily enough, it's generally a bad idea to change the constants. However, you should add to them where appropriate, for instance, if you intend to record new kinds of events in the log.

''There is nothing technically '''constant''' about the variables in constants.py - they could easily be modified at runtime. If you know how to define constants that are actually constant, or just of a better general approach, then this might be an area of the server that you could improve.''
--[[User:Xander|Xander]] 17:21, 18 July 2008 (BST)

===== data.py =====

data.py provides an interface to the database. Wherever XTS needs to get information from the database, it does it by calling a function in data.py. data.py then takes care of turning the information request into SQL, and if necessary, post-processing the response into a useful form for the caller.

You should be able to port XTS to another datastore simply by replacing data.py.

===== exceptions.py =====

exceptions.py defines the SnewtsError exception type. For more information, see [[#Error_Handling]].

===== helpers.py =====

helpers.py contains various functions that help to solve common and recurring problems in the Snewts application (for instance, turning datetime objects into human-readable date strings). This unclutters [[#logic.py]], which should just contain the business logic of how to sell tickets properly. Functions in helpers.py should ideally be moved into [[#XWF]], but who really cares?

===== logic.py =====

logic.py sits between the client request and the database. When the client asks to sell a ticket, logic.py makes sure that the show actually exists, the ticket is valid for the performance, there are enough tickets left and anything else that needs making sure of. If any one bit of XTS is going to get something critically wrong, it's going to be in logic.py.

logic.py never talks to the database directly. To get data from the database and make changes to the database it must call functions in [[#data.py]].

===== printer.py =====

printer.py is an abstraction layer with one synchronous public function, printTicket(). It takes care of sending the ticket to the [[#Print Server]] and making sure that the printer got the ticket. If the print can't be confirmed it throws a SnewtsError.

===== report.py =====

report.py contains all of the code that formats statistics gathered from the database into XML reports. It also does a little math. See [[#Reporting]].

===== snewts.py =====

snewts.py does the job of recognising requests from clients, checking that the clients are authorised to make the requests, and sending back responses. Simple requests (ie. getPerformances) are fulfilled by getting data from [[#data.py]] directly. More complicated requests are fulfilled by calling business logic in [[#logic.py]] or getting [[#report.py]] to generate reports.

===== status.py =====

status.py contains definitions of all of the errors that XTS may reply with when something goes wrong. If you're writing client software, you need to anticipate these coming back at you.

=== Print Server ===

The print server is a separate entity from the ticketing server that handles ticket printing. It listens on the network for messages instructing it to print tickets.

It is written in pure Java for the convenience of Java's layout and printing library. It uses the effective users' default printer for printing (so this printer needs to be set to the ticket printer).

==== API ====

The print server listens for tickets to print on port . Tickets are sent to the printer as UDP messages on port 8301. The UDP message format consists of six strings terminated by the NULL character. It does not support UTF8 encoding. It is very fail. The strings are, in order:

* Show Name
* Date (expected format: ddd YYYY-MM-DD)
* Time (expected format: HH:MM)
* Booking name (can be an empty string)
* Ticket serial
* Ticket type (ie. "Student")

When the print server receives your ticket and succeeds in dispatching it to the printer it will reply with a UDP packet containing the ticket serial you specified.

==== Making new ticket layouts ====

You need to know Java to write new ticket layouts.

Make a pair of new classes implementing uk.org.opentheatre.xts.Ticket and uk.org.opentheatre.xts.TicketFactory. The former must lay out the ticket, the latter must create instances of the ticket. Look at existing ticket classes for examples on how to do this.

Then, modify the uk.co.bedlamtheatre.BedlamTicketPrintServer to use your new TicketFactory class. You're now done. You can run your modified BedlamTicketPrintServer straight from your IDE and use the taskbar icon that appears to print test tickets and receive tickets from the XTS Ticket Server (if the print service isn't running - see [[#Startup - Windows Services]]). When you're happy with your new layout, replace the classes in C:\XTS\PrinterInterface\bin and either restart the Windows Service or just reboot.

==== Changing the Ticket Logo ====

This is much easier than making a new layout. Just replace C:\Xander\ticketlogo.bmp with your new logo. It should have the same dimensions and should probably be just black and white.

== Making Improvements - a HOWTO ==

=== Getting Started ===

==== Setting Up a Development Server ====

These are the steps I needed to take (and didn't need to take, but that you will need to on other platforms) to set up a development server on a new MacBook on 2008-08-27.

You need to be familiar with Terminal, and you'll be using the sudo command to do things as root. If these things sound frightening you should start by googling around a little.

* Install '''XCode Tools'''. You're going to need XCode so that you can build the Python/MySQL adapter later. You can download XCode from http://developer.apple.com/tools/xcode/. It's free, but it's a big download. While you're downloading it, move onto the next couple of steps.
* '''Python 2.5''' is already installed on Mac OS X 10.5. Rejoice.
* '''easy_install''' is already installed on Mac OS X 10.5. Aren't you glad you bought a Mac?
* Install a '''MySQL database server'''. It's free and open-source. http://dev.mysql.com
* '''Add the MySQL server binaries to your path'''. To do this you need to create a bash profile.
$ sudo emacs .bash_profile
Then, put this in the new file you've just created in EMACS:
export PATH=$PATH:/usr/local/mysql/bin
Then save and close your new profile by pressing CTRL-X, CTRL-S, XTRL-X, CTRL-C. Then to make use of your new profile, close and re-open your terminal.
* So long as the previous step went well you should now be able to '''start up your MySQL server''' by typing:
$ sudo safe_mysqld
If that fails to work, you didn't manage to reconfigure your path properly. Google for help.
* Install '''web.py'''
$ sudo easy_install web.py
* In order to run the administration interface, install '''Django'''. http://www.djangoproject.com/download/
* Build a '''Python/MySQL adapter'''. Download the tarball from http://sourceforge.net/projects/mysql-python. Then untar it, patch _mysql.c by hand and install. Sounds hard? It is. Hopefully by the time you come to do this, installing the mysql adapter will be as easy as sudo easy_install mysql_python. See http://forums.mysql.com/read.php?50,175059,219216#msg-219216 for more info.
$ tar -xvf MySQL-python-1.2.2.tar
$ cd MySQL-python-1.2.2
$ emacs _mysql.c (... and patch as shown on teh internets -- you need to comment out lines 37-39)
$ sudo python setup.py install
$ sudo mkdir /usr/local/mysql/lib/mysql
$ sudo cp /usr/local/mysql/lib/libmysqlclient_r.15.dylib /usr/local/mysql/lib/mysql/libmysqlclient_r.15.dylib
You've now finished installing all of the required software. Next you need to set up the initial data and permissions in the database.
* Download '''CocoaMySQL''', or an alternative MySQL client of your choosing.
* '''Log into your own MySQL server''' as root.
* '''Create a database''' called "xts".
* '''Import a database backup''' from Maude. It's the fastest way to get up and running with plenty of real-world data.
* '''Set permissions''' so that the anonymous user on localhost ("@localhost") has full access to the xts database. These are very lax permissions, but they'll do for a development server.
* Finally, '''run the XTS server'''. In whatever directory you have a copy of the XTS source, run:
$ python server.py
You can now visit http://localhost:8080 in a web browser on your own computer to play around. So long as the version signature under the XTS logo shows "DEV", you're looking at your own server.
* Get hacking.

Branding

2008-10-08T19:50:57Z

Xander: /* Edinburgh University Students Association */ New EUSA logo

== Current Branding ==

=== Bedlam Theatre ===

[[Image:Bedlamtheatrelogo2007.jpg|150px|left]]
 
The Bedlam Theatre logo should be shown on all Bedlam Theatre and EUTC related publicity.

The logo should be shown with its surrounding box though the border is optional if the box is shown in contrast to the poster background.

The current branding was designed by Nick Kay for the 2007 Fringe and 07/08 academic year. We are continuing the use of this branding.

 

* [http://wiki.eutc.org.uk/images/b/b5/Bedlamtheatrelogo2007.jpg Download a high-resolution JPEG of the Bedlam Theatre logo]
* [http://wiki.eutc.org.uk/images/1/11/BedlamLogoBW.eps Download a vector postscript of the Bedlam Theatre logo, black on white]
* [http://wiki.eutc.org.uk/images/1/12/BedlamLogoWB.eps Download a vector postscript of the Bedlam Theatre logo, white on black]

=== Edinburgh University Theatre Company ===

Currently the Edinburgh University Theatre Company shares the Bedlam Theatre brand, so does not have a specific logo of it's own. To show the involvement of the EUTC in the production on posters you may write "Edinburgh University Theatre Company presents..." or similar.

=== Edinburgh University Students Association ===

[[Image:Eusa-logo-2008.jpg|left|150px]]
 
All society posters displayed in University buildings must display the EUSA logo.

 

* [http://wiki.eutc.org.uk/images/5/5d/Eusa-logo-2008.jpg Download a high-resolution JPEG of the EUSA logo]
* [http://wiki.eutc.org.uk/images/2/20/Eusa-logo-2008.eps Download a vector postscript of the EUSA logo]

== Previous Brandings ==

These images should not be used on publicity. Please attribute these images if you can.

<gallery>
Image:Fringecat.gif|[[Fat Cat|No author]]
Image:Fatcat.gif|[[Fat Cat|No author]]
Image:Bedlameutc.gif
Image:Bedlam.gif
Image:100cat.gif
Image:Maintitle.gif
Image:Logo6.gif
Image:Logo.gif|Neil Hobbs
Image:Stamp k.jpg|Chris Mounsey
Image:Bedlam metal.jpg|Chris Mounsey
Image:Eutc bed metal.jpg|Chris Mounsey
Image:Eutc prod metal.jpg|Chris Mounsey

</gallery>

Branding

2008-10-08T19:50:24Z

Xander: /* Edinburgh University Students Association */

== Current Branding ==

=== Bedlam Theatre ===

[[Image:Bedlamtheatrelogo2007.jpg|150px|left]]
 
The Bedlam Theatre logo should be shown on all Bedlam Theatre and EUTC related publicity.

The logo should be shown with its surrounding box though the border is optional if the box is shown in contrast to the poster background.

The current branding was designed by Nick Kay for the 2007 Fringe and 07/08 academic year. We are continuing the use of this branding.

 

* [http://wiki.eutc.org.uk/images/b/b5/Bedlamtheatrelogo2007.jpg Download a high-resolution JPEG of the Bedlam Theatre logo]
* [http://wiki.eutc.org.uk/images/1/11/BedlamLogoBW.eps Download a vector postscript of the Bedlam Theatre logo, black on white]
* [http://wiki.eutc.org.uk/images/1/12/BedlamLogoWB.eps Download a vector postscript of the Bedlam Theatre logo, white on black]

=== Edinburgh University Theatre Company ===

Currently the Edinburgh University Theatre Company shares the Bedlam Theatre brand, so does not have a specific logo of it's own. To show the involvement of the EUTC in the production on posters you may write "Edinburgh University Theatre Company presents..." or similar.

=== Edinburgh University Students Association ===

[[Image:Eusa-logo-2008.jpg|left|150px]]
 
All society posters displayed in University buildings must display the EUSA logo.

 

* [http://wiki.eutc.org.uk/images/5/5d/Eusa-logo-2008.jpg Download a high-resolution JPEG of the EUSA logo]
* [http://wiki.eutc.org.uk/images/2/20/Eusa-logo-2008.eps Download a vector EPS of the EUSA logo]

== Previous Brandings ==

These images should not be used on publicity. Please attribute these images if you can.

<gallery>
Image:Fringecat.gif|[[Fat Cat|No author]]
Image:Fatcat.gif|[[Fat Cat|No author]]
Image:Bedlameutc.gif
Image:Bedlam.gif
Image:100cat.gif
Image:Maintitle.gif
Image:Logo6.gif
Image:Logo.gif|Neil Hobbs
Image:Stamp k.jpg|Chris Mounsey
Image:Bedlam metal.jpg|Chris Mounsey
Image:Eutc bed metal.jpg|Chris Mounsey
Image:Eutc prod metal.jpg|Chris Mounsey

</gallery>

File:Eusa-logo-2008.eps

2008-10-08T19:46:28Z

Xander: New EUSA logo in vector format.

New EUSA logo in vector format.

File:Eusa-logo-2008.jpg

2008-10-08T19:44:56Z

Xander: EUSA's new logo since 2008 - high resolution JPG

EUSA's new logo since 2008 - high resolution JPG

XTS

2008-08-28T15:38:48Z

Xander: /* What I plan to write about */

== eXtensible Ticketing System ==

XTS is the Bedlam Theatre's new ticketing system. It's key feature is extensibility, meaning that if it doesn't do something you want it to do, you (or a suitably inclined geek) should easily be able to add it. Read on for more key features and read further for technical information that will help you maintain and make changes to the system if that is your want.

If you are just looking for help using the software to sell tickets, try [[Using XTS]].

This page is a stub. I intend to document as much of the ticketing system as possible but keep forgetting things that I want to write about. Until it's completed, here's a list of sections that I intend to write under. This article is currently aimed at people who want to maintain the source code, NOT people who want to learn how to sell tickets.

== What I plan to write about ==

* History / Motivation
* Things you should know before you start
** Key Concepts and Terminology
*** "Reserved" vs. "Booked".
*** "Holding" tickets.
*** "Ticket Prototypes"
*** Verifying bookings
*** "Snewts"
*** How XTS handles times between 0AM and 3AM.
** Principles
*** Portability (OS Transparency)
*** Accessibility (Network Transparency)
*** Extensibility
*** Readability
*** Simplicity (Minimum Complexity in the Layers that Matter)
*** High-Level Scripting
* Technologies in use
** HTTP
** XML
** HTML
** CSS
** Python
** Java
* Parts of the system
** DONE Database
*** DONE Scheduled Database Backup
** DONE Ticket Server
*** DONE Web.py
*** DONE API
** DONE Print Server
*** DONE API
*** DONE Making new ticket layouts
*** DONE Changing the ticket logo
** Static Server
*** Apache 2.2
** Administration Server
** Javascript Client
*** Ami
*** Snewts
*** Prism
** Reporting
*** XSLT
** HTTPProxy
*** Protecting the ticketing server from the proxy
** Startup - Windows Services
*** JSWrapper
* Directory Structure (C:\XTS\)
* Installing XTS
* Making Improvements - A HOWTO
** Known Issues / Things you might like to work on
*** Sniffing attacks
*** No test suite, no TDD
*** Transactions (there aren't any)
*** Printing - it's pretty crap
*** Reports - XSLT, but not as it should be
** Familiarisation
*** Grokking the Source
** Tools You Must Use
*** Firebug
*** IPython
** Things You Must Do
*** DONE Setting up your own dev version from trunk
*** Keeping the documentation up-to-date
** Safe and Unsafe
*** Where is the money?
** Versioning
** Fun Ideas For Improvements or Otherwise
*** Booking from portable devices for producers ("Would you like to come? I'll book you a ticket now.")
*** XTS-controlled DMX for Box Office Lighting Fun Times
*** Heads-up displays for show times and sold out info a-la every cinema you've ever been to

= Documentation =

== Parts of the System ==

=== Database ===

XTS uses a MySQL database. It should be very easy to port XTS to other databases, most access is abstracted through [[#web.py]]'s db module but there may be some report-generating SQL queries that are specific to MySQL in the XTS source. See [[#data.py]] for more info.

The schema is called "xts".

==== Scheduled Database Backups ====

As of 2008-07-18, [[Maude]] is configured to take nightly backups of the XTS database to C:\XTS\Backups. These backups should be scaled back to weeklies or slower at the end of Fringe 2008 or they '''will''' eventually consume all available disk space on the machine. Furthermore the database should occasionally be backed up "off-site" in case of hard disk failure.

=== Ticket Server ===

The ticket server does the hard work of allocating, booking and selling tickets of various types for various performances of various shows. The ticket server is written in [[#Python]]. It is implemented on top of a web server ([http://www.webpy.org web.py]]), allowing clients to interact with the server via [[#HTTP]] using [[#XML]] for data exchange.

The ticket server is accessible via HTTP on port 8080.

==== API ====

API stands for Application Programming Interface. It tells you how you can write programs that talk to the ticket server in order to do useful things (like get show information, or sell tickets online).

The [[#Javascript Client]] uses the XTS API to make a nice box office interface for selling tickets to customers.

If you know a little XML and HTTP you can write programs that interact with the API yourself.

See [[XTS API]] for further information and full documentation.

==== Security ====

The ticket server uses host and password authentication to decide who can do what using the API. Full details are in the [[XTS API|API documentation]].

==== Error Handling ====

When the server encounters an error (for instance, a ticket that you are selling has already been sold), internally it throws a SnewtsError exception.

SnewtsErrors are caught by the request dispatcher (snewtsUrlInvocation in server.py) and turned into an XML-formatted error that is sent back to the client.

SnewtsErrors consist of an error number (useful to computers) and an error message (useful to people). Errors are grouped into types. For instance, all errors that start with the number 404 represent a requested thing not being there ("Not Found"). However, 404.1 specifically means that it was a ticket that wasn't found. 404.2 means a performance wasn't found and so on.

This is important when writing software that talk to the ticket server via the [[#API]]. When reading responses from the server the client software can have a default way of handling 404 errors but additionally can have a specific way of handling 404.5 errors.

Where possible, error numbers correspond to the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html HTTP status code definitions]. This is mostly because I'm perverse and think it's funny that when something isn't there you get a 404 error. However, it can be useful when writing your client software in that a 4xx error indicates that the client probably did something wrong whereas 5xx errors indicate that something went wrong on the server (which is potentially much more serious).

==== Source ====

Alphabetically:

===== constants.py =====

Contains various useful constants used in the rest of the XTS source. This makes the code more readable. In the database, the number 2 represents a ticket that is booked. However, instead of using the number 2 to refer to such tickets in the source code, we use the expression <code>ticketstates['BOOKED']</code>. This makes the code (a lot) more readable.

Funnily enough, it's generally a bad idea to change the constants. However, you should add to them where appropriate, for instance, if you intend to record new kinds of events in the log.

''There is nothing technically '''constant''' about the variables in constants.py - they could easily be modified at runtime. If you know how to define constants that are actually constant, or just of a better general approach, then this might be an area of the server that you could improve.''
--[[User:Xander|Xander]] 17:21, 18 July 2008 (BST)

===== data.py =====

data.py provides an interface to the database. Wherever XTS needs to get information from the database, it does it by calling a function in data.py. data.py then takes care of turning the information request into SQL, and if necessary, post-processing the response into a useful form for the caller.

You should be able to port XTS to another datastore simply by replacing data.py.

===== exceptions.py =====

exceptions.py defines the SnewtsError exception type. For more information, see [[#Error_Handling]].

===== helpers.py =====

helpers.py contains various functions that help to solve common and recurring problems in the Snewts application (for instance, turning datetime objects into human-readable date strings). This unclutters [[#logic.py]], which should just contain the business logic of how to sell tickets properly. Functions in helpers.py should ideally be moved into [[#XWF]], but who really cares?

===== logic.py =====

logic.py sits between the client request and the database. When the client asks to sell a ticket, logic.py makes sure that the show actually exists, the ticket is valid for the performance, there are enough tickets left and anything else that needs making sure of. If any one bit of XTS is going to get something critically wrong, it's going to be in logic.py.

logic.py never talks to the database directly. To get data from the database and make changes to the database it must call functions in [[#data.py]].

===== printer.py =====

printer.py is an abstraction layer with one synchronous public function, printTicket(). It takes care of sending the ticket to the [[#Print Server]] and making sure that the printer got the ticket. If the print can't be confirmed it throws a SnewtsError.

===== report.py =====

report.py contains all of the code that formats statistics gathered from the database into XML reports. It also does a little math. See [[#Reporting]].

===== snewts.py =====

snewts.py does the job of recognising requests from clients, checking that the clients are authorised to make the requests, and sending back responses. Simple requests (ie. getPerformances) are fulfilled by getting data from [[#data.py]] directly. More complicated requests are fulfilled by calling business logic in [[#logic.py]] or getting [[#report.py]] to generate reports.

===== status.py =====

status.py contains definitions of all of the errors that XTS may reply with when something goes wrong. If you're writing client software, you need to anticipate these coming back at you.

=== Print Server ===

The print server is a separate entity from the ticketing server that handles ticket printing. It listens on the network for messages instructing it to print tickets.

It is written in pure Java for the convenience of Java's layout and printing library. It uses the effective users' default printer for printing (so this printer needs to be set to the ticket printer).

==== API ====

The print server listens for tickets to print on port . Tickets are sent to the printer as UDP messages on port 8301. The UDP message format consists of six strings terminated by the NULL character. It does not support UTF8 encoding. It is very fail. The strings are, in order:

* Show Name
* Date (expected format: ddd YYYY-MM-DD)
* Time (expected format: HH:MM)
* Booking name (can be an empty string)
* Ticket serial
* Ticket type (ie. "Student")

When the print server receives your ticket and succeeds in dispatching it to the printer it will reply with a UDP packet containing the ticket serial you specified.

==== Making new ticket layouts ====

You need to know Java to write new ticket layouts.

Make a pair of new classes implementing uk.org.opentheatre.xts.Ticket and uk.org.opentheatre.xts.TicketFactory. The former must lay out the ticket, the latter must create instances of the ticket. Look at existing ticket classes for examples on how to do this.

Then, modify the uk.co.bedlamtheatre.BedlamTicketPrintServer to use your new TicketFactory class. You're now done. You can run your modified BedlamTicketPrintServer straight from your IDE and use the taskbar icon that appears to print test tickets and receive tickets from the XTS Ticket Server (if the print service isn't running - see [[#Startup - Windows Services]]). When you're happy with your new layout, replace the classes in C:\XTS\PrinterInterface\bin and either restart the Windows Service or just reboot.

==== Changing the Ticket Logo ====

This is much easier than making a new layout. Just replace C:\Xander\ticketlogo.bmp with your new logo. It should have the same dimensions and should probably be just black and white.

== Making Improvements - a HOWTO ==

=== Getting Started ===

==== Setting Up a Development Server ====

These are the steps I needed to take (and didn't need to take, but that you will need to on other platforms) to set up a development server on a new MacBook on 2008-08-27.

You need to be familiar with Terminal, and you'll be using the sudo command to do things as root. If these things sound frightening you should start by googling around a little.

* Install '''XCode Tools'''. You're going to need XCode so that you can build the Python/MySQL adapter later. You can download XCode from http://developer.apple.com/tools/xcode/. It's free, but it's a big download. While you're downloading it, move onto the next couple of steps.
* '''Python 2.5''' is already installed on Mac OS X 10.5. Rejoice.
* '''easy_install''' is already installed on Mac OS X 10.5. Aren't you glad you bought a Mac?
* Install a '''MySQL database server'''. It's free and open-source. http://dev.mysql.com
* '''Add the MySQL server binaries to your path'''. To do this you need to create a bash profile.
$ sudo emacs .bash_profile
Then, put this in the new file you've just created in EMACS:
export PATH=$PATH:/usr/local/mysql/bin
Then save and close your new profile by pressing CTRL-X, CTRL-S, XTRL-X, CTRL-C. Then to make use of your new profile, close and re-open your terminal.
* So long as the previous step went well you should now be able to '''start up your MySQL server''' by typing:
$ sudo safe_mysqld
If that fails to work, you didn't manage to reconfigure your path properly. Google for help.
* Install '''web.py'''
$ sudo easy_install web.py
* In order to run the administration interface, install '''Django'''. http://www.djangoproject.com/download/
* Build a '''Python/MySQL adapter'''. Download the tarball from http://sourceforge.net/projects/mysql-python. Then untar it, patch _mysql.c by hand and install. Sounds hard? It is. Hopefully by the time you come to do this, installing the mysql adapter will be as easy as sudo easy_install mysql_python. See http://forums.mysql.com/read.php?50,175059,219216#msg-219216 for more info.
$ tar -xvf MySQL-python-1.2.2.tar
$ cd MySQL-python-1.2.2
$ emacs _mysql.c (... and patch as shown on teh internets -- you need to comment out lines 37-39)
$ sudo python setup.py install
$ sudo mkdir /usr/local/mysql/lib/mysql
$ sudo cp /usr/local/mysql/lib/libmysqlclient_r.15.dylib /usr/local/mysql/lib/mysql/libmysqlclient_r.15.dylib
You've now finished installing all of the required software. Next you need to set up the initial data and permissions in the database.
* Download '''CocoaMySQL''', or an alternative MySQL client of your choosing.
* '''Log into your own MySQL server''' as root.
* '''Create a database''' called "xts".
* '''Import a database backup''' from Maude. It's the fastest way to get up and running with plenty of real-world data.
* '''Set permissions''' so that the anonymous user on localhost ("@localhost") has full access to the xts database. These are very lax permissions, but they'll do for a development server.
* Finally, '''run the XTS server'''. In whatever directory you have a copy of the XTS source, run:
$ python server.py
You can now visit http://localhost:8080 in a web browser on your own computer to play around. So long as the version signature under the XTS logo shows "DEV", you're looking at your own server.
* Get hacking.

XTS

2008-08-28T15:23:45Z

Xander: /* Setting Up a Development Server */

== eXtensible Ticketing System ==

XTS is the Bedlam Theatre's new ticketing system. It's key feature is extensibility, meaning that if it doesn't do something you want it to do, you (or a suitably inclined geek) should easily be able to add it. Read on for more key features and read further for technical information that will help you maintain and make changes to the system if that is your want.

If you are just looking for help using the software to sell tickets, try [[Using XTS]].

This page is a stub. I intend to document as much of the ticketing system as possible but keep forgetting things that I want to write about. Until it's completed, here's a list of sections that I intend to write under. This article is currently aimed at people who want to maintain the source code, NOT people who want to learn how to sell tickets.

== What I plan to write about ==

* History / Motivation
* Things you should know before you start
** Key Concepts and Terminology
*** "Reserved" vs. "Booked".
*** "Holding" tickets.
*** "Ticket Prototypes"
*** Verifying bookings
*** "Snewts"
*** How XTS handles times between 0AM and 3AM.
** Principles
*** Portability (OS Transparency)
*** Accessibility (Network Transparency)
*** Extensibility
*** Readability
*** Simplicity (Minimum Complexity in the Layers that Matter)
*** High-Level Scripting
* Technologies in use
** HTTP
** XML
** HTML
** CSS
** Python
** Java
* Parts of the system
** DONE Database
*** DONE Scheduled Database Backup
** DONE Ticket Server
*** DONE Web.py
*** DONE API
** DONE Print Server
*** DONE API
*** DONE Making new ticket layouts
*** DONE Changing the ticket logo
** Static Server
*** Apache 2.2
** Administration Server
** Javascript Client
*** Ami
*** Snewts
*** Prism
** Reporting
*** XSLT
** HTTPProxy
*** Protecting the ticketing server from the proxy
** Startup - Windows Services
*** JSWrapper
* Directory Structure (C:\XTS\)
* Installing XTS
* Making Improvements - A HOWTO
** Known Issues / Things you might like to work on
*** Sniffing attacks
*** No test suite, no TDD
*** Transactions (there aren't any)
*** Printing - it's pretty crap
*** Reports - XSLT, but not as it should be
** Familiarisation
*** Grokking the Source
** Tools You Must Use
*** Firebug
*** IPython
** Things You Must Do
*** Setting up your own dev version from trunk
*** Working on a test data set
*** Keeping the documentation up-to-date
** Safe and Unsafe
*** Where is the money?
** Versioning
** Fun Ideas For Improvements or Otherwise
*** Booking from portable devices for producers ("Would you like to come? I'll book you a ticket now.")
*** XTS-controlled DMX for Box Office Lighting Fun Times
*** Heads-up displays for show times and sold out info a-la every cinema you've ever been to

= Documentation =

== Parts of the System ==

=== Database ===

XTS uses a MySQL database. It should be very easy to port XTS to other databases, most access is abstracted through [[#web.py]]'s db module but there may be some report-generating SQL queries that are specific to MySQL in the XTS source. See [[#data.py]] for more info.

The schema is called "xts".

==== Scheduled Database Backups ====

As of 2008-07-18, [[Maude]] is configured to take nightly backups of the XTS database to C:\XTS\Backups. These backups should be scaled back to weeklies or slower at the end of Fringe 2008 or they '''will''' eventually consume all available disk space on the machine. Furthermore the database should occasionally be backed up "off-site" in case of hard disk failure.

=== Ticket Server ===

The ticket server does the hard work of allocating, booking and selling tickets of various types for various performances of various shows. The ticket server is written in [[#Python]]. It is implemented on top of a web server ([http://www.webpy.org web.py]]), allowing clients to interact with the server via [[#HTTP]] using [[#XML]] for data exchange.

The ticket server is accessible via HTTP on port 8080.

==== API ====

API stands for Application Programming Interface. It tells you how you can write programs that talk to the ticket server in order to do useful things (like get show information, or sell tickets online).

The [[#Javascript Client]] uses the XTS API to make a nice box office interface for selling tickets to customers.

If you know a little XML and HTTP you can write programs that interact with the API yourself.

See [[XTS API]] for further information and full documentation.

==== Security ====

The ticket server uses host and password authentication to decide who can do what using the API. Full details are in the [[XTS API|API documentation]].

==== Error Handling ====

When the server encounters an error (for instance, a ticket that you are selling has already been sold), internally it throws a SnewtsError exception.

SnewtsErrors are caught by the request dispatcher (snewtsUrlInvocation in server.py) and turned into an XML-formatted error that is sent back to the client.

SnewtsErrors consist of an error number (useful to computers) and an error message (useful to people). Errors are grouped into types. For instance, all errors that start with the number 404 represent a requested thing not being there ("Not Found"). However, 404.1 specifically means that it was a ticket that wasn't found. 404.2 means a performance wasn't found and so on.

This is important when writing software that talk to the ticket server via the [[#API]]. When reading responses from the server the client software can have a default way of handling 404 errors but additionally can have a specific way of handling 404.5 errors.

Where possible, error numbers correspond to the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html HTTP status code definitions]. This is mostly because I'm perverse and think it's funny that when something isn't there you get a 404 error. However, it can be useful when writing your client software in that a 4xx error indicates that the client probably did something wrong whereas 5xx errors indicate that something went wrong on the server (which is potentially much more serious).

==== Source ====

Alphabetically:

===== constants.py =====

Contains various useful constants used in the rest of the XTS source. This makes the code more readable. In the database, the number 2 represents a ticket that is booked. However, instead of using the number 2 to refer to such tickets in the source code, we use the expression <code>ticketstates['BOOKED']</code>. This makes the code (a lot) more readable.

Funnily enough, it's generally a bad idea to change the constants. However, you should add to them where appropriate, for instance, if you intend to record new kinds of events in the log.

''There is nothing technically '''constant''' about the variables in constants.py - they could easily be modified at runtime. If you know how to define constants that are actually constant, or just of a better general approach, then this might be an area of the server that you could improve.''
--[[User:Xander|Xander]] 17:21, 18 July 2008 (BST)

===== data.py =====

data.py provides an interface to the database. Wherever XTS needs to get information from the database, it does it by calling a function in data.py. data.py then takes care of turning the information request into SQL, and if necessary, post-processing the response into a useful form for the caller.

You should be able to port XTS to another datastore simply by replacing data.py.

===== exceptions.py =====

exceptions.py defines the SnewtsError exception type. For more information, see [[#Error_Handling]].

===== helpers.py =====

helpers.py contains various functions that help to solve common and recurring problems in the Snewts application (for instance, turning datetime objects into human-readable date strings). This unclutters [[#logic.py]], which should just contain the business logic of how to sell tickets properly. Functions in helpers.py should ideally be moved into [[#XWF]], but who really cares?

===== logic.py =====

logic.py sits between the client request and the database. When the client asks to sell a ticket, logic.py makes sure that the show actually exists, the ticket is valid for the performance, there are enough tickets left and anything else that needs making sure of. If any one bit of XTS is going to get something critically wrong, it's going to be in logic.py.

logic.py never talks to the database directly. To get data from the database and make changes to the database it must call functions in [[#data.py]].

===== printer.py =====

printer.py is an abstraction layer with one synchronous public function, printTicket(). It takes care of sending the ticket to the [[#Print Server]] and making sure that the printer got the ticket. If the print can't be confirmed it throws a SnewtsError.

===== report.py =====

report.py contains all of the code that formats statistics gathered from the database into XML reports. It also does a little math. See [[#Reporting]].

===== snewts.py =====

snewts.py does the job of recognising requests from clients, checking that the clients are authorised to make the requests, and sending back responses. Simple requests (ie. getPerformances) are fulfilled by getting data from [[#data.py]] directly. More complicated requests are fulfilled by calling business logic in [[#logic.py]] or getting [[#report.py]] to generate reports.

===== status.py =====

status.py contains definitions of all of the errors that XTS may reply with when something goes wrong. If you're writing client software, you need to anticipate these coming back at you.

=== Print Server ===

The print server is a separate entity from the ticketing server that handles ticket printing. It listens on the network for messages instructing it to print tickets.

It is written in pure Java for the convenience of Java's layout and printing library. It uses the effective users' default printer for printing (so this printer needs to be set to the ticket printer).

==== API ====

The print server listens for tickets to print on port . Tickets are sent to the printer as UDP messages on port 8301. The UDP message format consists of six strings terminated by the NULL character. It does not support UTF8 encoding. It is very fail. The strings are, in order:

* Show Name
* Date (expected format: ddd YYYY-MM-DD)
* Time (expected format: HH:MM)
* Booking name (can be an empty string)
* Ticket serial
* Ticket type (ie. "Student")

When the print server receives your ticket and succeeds in dispatching it to the printer it will reply with a UDP packet containing the ticket serial you specified.

==== Making new ticket layouts ====

You need to know Java to write new ticket layouts.

Make a pair of new classes implementing uk.org.opentheatre.xts.Ticket and uk.org.opentheatre.xts.TicketFactory. The former must lay out the ticket, the latter must create instances of the ticket. Look at existing ticket classes for examples on how to do this.

Then, modify the uk.co.bedlamtheatre.BedlamTicketPrintServer to use your new TicketFactory class. You're now done. You can run your modified BedlamTicketPrintServer straight from your IDE and use the taskbar icon that appears to print test tickets and receive tickets from the XTS Ticket Server (if the print service isn't running - see [[#Startup - Windows Services]]). When you're happy with your new layout, replace the classes in C:\XTS\PrinterInterface\bin and either restart the Windows Service or just reboot.

==== Changing the Ticket Logo ====

This is much easier than making a new layout. Just replace C:\Xander\ticketlogo.bmp with your new logo. It should have the same dimensions and should probably be just black and white.

== Making Improvements - a HOWTO ==

=== Getting Started ===

==== Setting Up a Development Server ====

These are the steps I needed to take (and didn't need to take, but that you will need to on other platforms) to set up a development server on a new MacBook on 2008-08-27.

You need to be familiar with Terminal, and you'll be using the sudo command to do things as root. If these things sound frightening you should start by googling around a little.

* Install '''XCode Tools'''. You're going to need XCode so that you can build the Python/MySQL adapter later. You can download XCode from http://developer.apple.com/tools/xcode/. It's free, but it's a big download. While you're downloading it, move onto the next couple of steps.
* '''Python 2.5''' is already installed on Mac OS X 10.5. Rejoice.
* '''easy_install''' is already installed on Mac OS X 10.5. Aren't you glad you bought a Mac?
* Install a '''MySQL database server'''. It's free and open-source. http://dev.mysql.com
* '''Add the MySQL server binaries to your path'''. To do this you need to create a bash profile.
$ sudo emacs .bash_profile
Then, put this in the new file you've just created in EMACS:
export PATH=$PATH:/usr/local/mysql/bin
Then save and close your new profile by pressing CTRL-X, CTRL-S, XTRL-X, CTRL-C. Then to make use of your new profile, close and re-open your terminal.
* So long as the previous step went well you should now be able to '''start up your MySQL server''' by typing:
$ sudo safe_mysqld
If that fails to work, you didn't manage to reconfigure your path properly. Google for help.
* Install '''web.py'''
$ sudo easy_install web.py
* In order to run the administration interface, install '''Django'''. http://www.djangoproject.com/download/
* Build a '''Python/MySQL adapter'''. Download the tarball from http://sourceforge.net/projects/mysql-python. Then untar it, patch _mysql.c by hand and install. Sounds hard? It is. Hopefully by the time you come to do this, installing the mysql adapter will be as easy as sudo easy_install mysql_python. See http://forums.mysql.com/read.php?50,175059,219216#msg-219216 for more info.
$ tar -xvf MySQL-python-1.2.2.tar
$ cd MySQL-python-1.2.2
$ emacs _mysql.c (... and patch as shown on teh internets -- you need to comment out lines 37-39)
$ sudo python setup.py install
$ sudo mkdir /usr/local/mysql/lib/mysql
$ sudo cp /usr/local/mysql/lib/libmysqlclient_r.15.dylib /usr/local/mysql/lib/mysql/libmysqlclient_r.15.dylib
You've now finished installing all of the required software. Next you need to set up the initial data and permissions in the database.
* Download '''CocoaMySQL''', or an alternative MySQL client of your choosing.
* '''Log into your own MySQL server''' as root.
* '''Create a database''' called "xts".
* '''Import a database backup''' from Maude. It's the fastest way to get up and running with plenty of real-world data.
* '''Set permissions''' so that the anonymous user on localhost ("@localhost") has full access to the xts database. These are very lax permissions, but they'll do for a development server.
* Finally, '''run the XTS server'''. In whatever directory you have a copy of the XTS source, run:
$ python server.py
You can now visit http://localhost:8080 in a web browser on your own computer to play around. So long as the version signature under the XTS logo shows "DEV", you're looking at your own server.
* Get hacking.

XTS

2008-08-28T15:22:16Z

Xander: /* Setting Up a Development Server */

== eXtensible Ticketing System ==

XTS is the Bedlam Theatre's new ticketing system. It's key feature is extensibility, meaning that if it doesn't do something you want it to do, you (or a suitably inclined geek) should easily be able to add it. Read on for more key features and read further for technical information that will help you maintain and make changes to the system if that is your want.

If you are just looking for help using the software to sell tickets, try [[Using XTS]].

This page is a stub. I intend to document as much of the ticketing system as possible but keep forgetting things that I want to write about. Until it's completed, here's a list of sections that I intend to write under. This article is currently aimed at people who want to maintain the source code, NOT people who want to learn how to sell tickets.

== What I plan to write about ==

* History / Motivation
* Things you should know before you start
** Key Concepts and Terminology
*** "Reserved" vs. "Booked".
*** "Holding" tickets.
*** "Ticket Prototypes"
*** Verifying bookings
*** "Snewts"
*** How XTS handles times between 0AM and 3AM.
** Principles
*** Portability (OS Transparency)
*** Accessibility (Network Transparency)
*** Extensibility
*** Readability
*** Simplicity (Minimum Complexity in the Layers that Matter)
*** High-Level Scripting
* Technologies in use
** HTTP
** XML
** HTML
** CSS
** Python
** Java
* Parts of the system
** DONE Database
*** DONE Scheduled Database Backup
** DONE Ticket Server
*** DONE Web.py
*** DONE API
** DONE Print Server
*** DONE API
*** DONE Making new ticket layouts
*** DONE Changing the ticket logo
** Static Server
*** Apache 2.2
** Administration Server
** Javascript Client
*** Ami
*** Snewts
*** Prism
** Reporting
*** XSLT
** HTTPProxy
*** Protecting the ticketing server from the proxy
** Startup - Windows Services
*** JSWrapper
* Directory Structure (C:\XTS\)
* Installing XTS
* Making Improvements - A HOWTO
** Known Issues / Things you might like to work on
*** Sniffing attacks
*** No test suite, no TDD
*** Transactions (there aren't any)
*** Printing - it's pretty crap
*** Reports - XSLT, but not as it should be
** Familiarisation
*** Grokking the Source
** Tools You Must Use
*** Firebug
*** IPython
** Things You Must Do
*** Setting up your own dev version from trunk
*** Working on a test data set
*** Keeping the documentation up-to-date
** Safe and Unsafe
*** Where is the money?
** Versioning
** Fun Ideas For Improvements or Otherwise
*** Booking from portable devices for producers ("Would you like to come? I'll book you a ticket now.")
*** XTS-controlled DMX for Box Office Lighting Fun Times
*** Heads-up displays for show times and sold out info a-la every cinema you've ever been to

= Documentation =

== Parts of the System ==

=== Database ===

XTS uses a MySQL database. It should be very easy to port XTS to other databases, most access is abstracted through [[#web.py]]'s db module but there may be some report-generating SQL queries that are specific to MySQL in the XTS source. See [[#data.py]] for more info.

The schema is called "xts".

==== Scheduled Database Backups ====

As of 2008-07-18, [[Maude]] is configured to take nightly backups of the XTS database to C:\XTS\Backups. These backups should be scaled back to weeklies or slower at the end of Fringe 2008 or they '''will''' eventually consume all available disk space on the machine. Furthermore the database should occasionally be backed up "off-site" in case of hard disk failure.

=== Ticket Server ===

The ticket server does the hard work of allocating, booking and selling tickets of various types for various performances of various shows. The ticket server is written in [[#Python]]. It is implemented on top of a web server ([http://www.webpy.org web.py]]), allowing clients to interact with the server via [[#HTTP]] using [[#XML]] for data exchange.

The ticket server is accessible via HTTP on port 8080.

==== API ====

API stands for Application Programming Interface. It tells you how you can write programs that talk to the ticket server in order to do useful things (like get show information, or sell tickets online).

The [[#Javascript Client]] uses the XTS API to make a nice box office interface for selling tickets to customers.

If you know a little XML and HTTP you can write programs that interact with the API yourself.

See [[XTS API]] for further information and full documentation.

==== Security ====

The ticket server uses host and password authentication to decide who can do what using the API. Full details are in the [[XTS API|API documentation]].

==== Error Handling ====

When the server encounters an error (for instance, a ticket that you are selling has already been sold), internally it throws a SnewtsError exception.

SnewtsErrors are caught by the request dispatcher (snewtsUrlInvocation in server.py) and turned into an XML-formatted error that is sent back to the client.

SnewtsErrors consist of an error number (useful to computers) and an error message (useful to people). Errors are grouped into types. For instance, all errors that start with the number 404 represent a requested thing not being there ("Not Found"). However, 404.1 specifically means that it was a ticket that wasn't found. 404.2 means a performance wasn't found and so on.

This is important when writing software that talk to the ticket server via the [[#API]]. When reading responses from the server the client software can have a default way of handling 404 errors but additionally can have a specific way of handling 404.5 errors.

Where possible, error numbers correspond to the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html HTTP status code definitions]. This is mostly because I'm perverse and think it's funny that when something isn't there you get a 404 error. However, it can be useful when writing your client software in that a 4xx error indicates that the client probably did something wrong whereas 5xx errors indicate that something went wrong on the server (which is potentially much more serious).

==== Source ====

Alphabetically:

===== constants.py =====

Contains various useful constants used in the rest of the XTS source. This makes the code more readable. In the database, the number 2 represents a ticket that is booked. However, instead of using the number 2 to refer to such tickets in the source code, we use the expression <code>ticketstates['BOOKED']</code>. This makes the code (a lot) more readable.

Funnily enough, it's generally a bad idea to change the constants. However, you should add to them where appropriate, for instance, if you intend to record new kinds of events in the log.

''There is nothing technically '''constant''' about the variables in constants.py - they could easily be modified at runtime. If you know how to define constants that are actually constant, or just of a better general approach, then this might be an area of the server that you could improve.''
--[[User:Xander|Xander]] 17:21, 18 July 2008 (BST)

===== data.py =====

data.py provides an interface to the database. Wherever XTS needs to get information from the database, it does it by calling a function in data.py. data.py then takes care of turning the information request into SQL, and if necessary, post-processing the response into a useful form for the caller.

You should be able to port XTS to another datastore simply by replacing data.py.

===== exceptions.py =====

exceptions.py defines the SnewtsError exception type. For more information, see [[#Error_Handling]].

===== helpers.py =====

helpers.py contains various functions that help to solve common and recurring problems in the Snewts application (for instance, turning datetime objects into human-readable date strings). This unclutters [[#logic.py]], which should just contain the business logic of how to sell tickets properly. Functions in helpers.py should ideally be moved into [[#XWF]], but who really cares?

===== logic.py =====

logic.py sits between the client request and the database. When the client asks to sell a ticket, logic.py makes sure that the show actually exists, the ticket is valid for the performance, there are enough tickets left and anything else that needs making sure of. If any one bit of XTS is going to get something critically wrong, it's going to be in logic.py.

logic.py never talks to the database directly. To get data from the database and make changes to the database it must call functions in [[#data.py]].

===== printer.py =====

printer.py is an abstraction layer with one synchronous public function, printTicket(). It takes care of sending the ticket to the [[#Print Server]] and making sure that the printer got the ticket. If the print can't be confirmed it throws a SnewtsError.

===== report.py =====

report.py contains all of the code that formats statistics gathered from the database into XML reports. It also does a little math. See [[#Reporting]].

===== snewts.py =====

snewts.py does the job of recognising requests from clients, checking that the clients are authorised to make the requests, and sending back responses. Simple requests (ie. getPerformances) are fulfilled by getting data from [[#data.py]] directly. More complicated requests are fulfilled by calling business logic in [[#logic.py]] or getting [[#report.py]] to generate reports.

===== status.py =====

status.py contains definitions of all of the errors that XTS may reply with when something goes wrong. If you're writing client software, you need to anticipate these coming back at you.

=== Print Server ===

The print server is a separate entity from the ticketing server that handles ticket printing. It listens on the network for messages instructing it to print tickets.

It is written in pure Java for the convenience of Java's layout and printing library. It uses the effective users' default printer for printing (so this printer needs to be set to the ticket printer).

==== API ====

The print server listens for tickets to print on port . Tickets are sent to the printer as UDP messages on port 8301. The UDP message format consists of six strings terminated by the NULL character. It does not support UTF8 encoding. It is very fail. The strings are, in order:

* Show Name
* Date (expected format: ddd YYYY-MM-DD)
* Time (expected format: HH:MM)
* Booking name (can be an empty string)
* Ticket serial
* Ticket type (ie. "Student")

When the print server receives your ticket and succeeds in dispatching it to the printer it will reply with a UDP packet containing the ticket serial you specified.

==== Making new ticket layouts ====

You need to know Java to write new ticket layouts.

Make a pair of new classes implementing uk.org.opentheatre.xts.Ticket and uk.org.opentheatre.xts.TicketFactory. The former must lay out the ticket, the latter must create instances of the ticket. Look at existing ticket classes for examples on how to do this.

Then, modify the uk.co.bedlamtheatre.BedlamTicketPrintServer to use your new TicketFactory class. You're now done. You can run your modified BedlamTicketPrintServer straight from your IDE and use the taskbar icon that appears to print test tickets and receive tickets from the XTS Ticket Server (if the print service isn't running - see [[#Startup - Windows Services]]). When you're happy with your new layout, replace the classes in C:\XTS\PrinterInterface\bin and either restart the Windows Service or just reboot.

==== Changing the Ticket Logo ====

This is much easier than making a new layout. Just replace C:\Xander\ticketlogo.bmp with your new logo. It should have the same dimensions and should probably be just black and white.

== Making Improvements - a HOWTO ==

=== Getting Started ===

==== Setting Up a Development Server ====

These are the steps I needed to take (and didn't need to take, but that you will need to on other platforms) to set up a development server on a new MacBook on 2008-08-27.

You need to be familiar with Terminal, and you'll be using the sudo command to do things as root. If these things sound frightening you should start by googling around a little.

* Install '''XCode Tools'''. You're going to need XCode so that you can build the Python/MySQL adapter later. You can download XCode from http://developer.apple.com/tools/xcode/. It's free, but it's a big download. While you're downloading it, move onto the next couple of steps.
* '''Python 2.5''' is already installed on Mac OS X 10.5. Rejoice.
* '''easy_install''' is already installed on Mac OS X 10.5. Aren't you glad you bought a Mac?
* Install a '''MySQL database server'''. It's free and open-source. http://dev.mysql.com
* '''Add the MySQL server binaries to your path'''. To do this you need to create a bash profile.
$ sudo emacs .bash_profile
Then, put this in the new file you've just created in EMACS:
export PATH=$PATH:/usr/local/mysql/bin
Then save and close your new profile by pressing CTRL-X, CTRL-S, XTRL-X, CTRL-C. Then to make use of your new profile, close and re-open your terminal.
* So long as the previous step went well you should now be able to '''start up your MySQL server''' by typing:
$ sudo safe_mysqld
If that fails to work, you didn't manage to reconfigure your path properly. Google for help.
* Install '''web.py'''
$ sudo easy_install web.py
* In order to run the administration interface, install '''Django'''. http://www.djangoproject.com/download/
* Build a '''Python/MySQL adapter'''. Download the tarball from http://sourceforge.net/projects/mysql-python. Then untar it, patch _mysql.c by hand and install. Sounds hard? It is. Hopefully by the time you come to do this, installing mysql will be as easy as sudo easy_install mysql_python. See http://forums.mysql.com/read.php?50,175059,219216#msg-219216 for more info.
$ tar -xvf MySQL-python-1.2.2.tar
$ cd MySQL-python-1.2.2
$ emacs _mysql.c (... and patch as shown on teh internets -- you need to comment out lines 37-39)
$ sudo python setup.py install
$ sudo mkdir /usr/local/mysql/lib/mysql
$ sudo cp /usr/local/mysql/lib/libmysqlclient_r.15.dylib /usr/local/mysql/lib/mysql/libmysqlclient_r.15.dylib
You've now finished installing all of the required software. Next you need to set up the initial data and permissions in the database.
* Download '''CocoaMySQL''', or an alternative MySQL client of your choosing.
* '''Log into your own MySQL server''' as root.
* '''Create a database''' called "xts".
* '''Import a database backup''' from Maude. It's the fastest way to get up and running with plenty of real-world data.
* '''Set permissions''' so that the anonymous user on localhost ("@localhost") has full access to the xts database. These are very lax permissions, but they'll do for a development server.
* Finally, '''run the XTS server'''. In whatever directory you have a copy of the XTS source, run:
$ python server.py
You can now visit http://localhost:8080 in a web browser on your own computer to play around. So long as the version signature under the XTS logo shows "DEV", you're looking at your own server.
* Get hacking.

XTS

2008-08-28T15:19:25Z

Xander: /* Setting Up a Development Server */

== eXtensible Ticketing System ==

XTS is the Bedlam Theatre's new ticketing system. It's key feature is extensibility, meaning that if it doesn't do something you want it to do, you (or a suitably inclined geek) should easily be able to add it. Read on for more key features and read further for technical information that will help you maintain and make changes to the system if that is your want.

If you are just looking for help using the software to sell tickets, try [[Using XTS]].

This page is a stub. I intend to document as much of the ticketing system as possible but keep forgetting things that I want to write about. Until it's completed, here's a list of sections that I intend to write under. This article is currently aimed at people who want to maintain the source code, NOT people who want to learn how to sell tickets.

== What I plan to write about ==

* History / Motivation
* Things you should know before you start
** Key Concepts and Terminology
*** "Reserved" vs. "Booked".
*** "Holding" tickets.
*** "Ticket Prototypes"
*** Verifying bookings
*** "Snewts"
*** How XTS handles times between 0AM and 3AM.
** Principles
*** Portability (OS Transparency)
*** Accessibility (Network Transparency)
*** Extensibility
*** Readability
*** Simplicity (Minimum Complexity in the Layers that Matter)
*** High-Level Scripting
* Technologies in use
** HTTP
** XML
** HTML
** CSS
** Python
** Java
* Parts of the system
** DONE Database
*** DONE Scheduled Database Backup
** DONE Ticket Server
*** DONE Web.py
*** DONE API
** DONE Print Server
*** DONE API
*** DONE Making new ticket layouts
*** DONE Changing the ticket logo
** Static Server
*** Apache 2.2
** Administration Server
** Javascript Client
*** Ami
*** Snewts
*** Prism
** Reporting
*** XSLT
** HTTPProxy
*** Protecting the ticketing server from the proxy
** Startup - Windows Services
*** JSWrapper
* Directory Structure (C:\XTS\)
* Installing XTS
* Making Improvements - A HOWTO
** Known Issues / Things you might like to work on
*** Sniffing attacks
*** No test suite, no TDD
*** Transactions (there aren't any)
*** Printing - it's pretty crap
*** Reports - XSLT, but not as it should be
** Familiarisation
*** Grokking the Source
** Tools You Must Use
*** Firebug
*** IPython
** Things You Must Do
*** Setting up your own dev version from trunk
*** Working on a test data set
*** Keeping the documentation up-to-date
** Safe and Unsafe
*** Where is the money?
** Versioning
** Fun Ideas For Improvements or Otherwise
*** Booking from portable devices for producers ("Would you like to come? I'll book you a ticket now.")
*** XTS-controlled DMX for Box Office Lighting Fun Times
*** Heads-up displays for show times and sold out info a-la every cinema you've ever been to

= Documentation =

== Parts of the System ==

=== Database ===

XTS uses a MySQL database. It should be very easy to port XTS to other databases, most access is abstracted through [[#web.py]]'s db module but there may be some report-generating SQL queries that are specific to MySQL in the XTS source. See [[#data.py]] for more info.

The schema is called "xts".

==== Scheduled Database Backups ====

As of 2008-07-18, [[Maude]] is configured to take nightly backups of the XTS database to C:\XTS\Backups. These backups should be scaled back to weeklies or slower at the end of Fringe 2008 or they '''will''' eventually consume all available disk space on the machine. Furthermore the database should occasionally be backed up "off-site" in case of hard disk failure.

=== Ticket Server ===

The ticket server does the hard work of allocating, booking and selling tickets of various types for various performances of various shows. The ticket server is written in [[#Python]]. It is implemented on top of a web server ([http://www.webpy.org web.py]]), allowing clients to interact with the server via [[#HTTP]] using [[#XML]] for data exchange.

The ticket server is accessible via HTTP on port 8080.

==== API ====

API stands for Application Programming Interface. It tells you how you can write programs that talk to the ticket server in order to do useful things (like get show information, or sell tickets online).

The [[#Javascript Client]] uses the XTS API to make a nice box office interface for selling tickets to customers.

If you know a little XML and HTTP you can write programs that interact with the API yourself.

See [[XTS API]] for further information and full documentation.

==== Security ====

The ticket server uses host and password authentication to decide who can do what using the API. Full details are in the [[XTS API|API documentation]].

==== Error Handling ====

When the server encounters an error (for instance, a ticket that you are selling has already been sold), internally it throws a SnewtsError exception.

SnewtsErrors are caught by the request dispatcher (snewtsUrlInvocation in server.py) and turned into an XML-formatted error that is sent back to the client.

SnewtsErrors consist of an error number (useful to computers) and an error message (useful to people). Errors are grouped into types. For instance, all errors that start with the number 404 represent a requested thing not being there ("Not Found"). However, 404.1 specifically means that it was a ticket that wasn't found. 404.2 means a performance wasn't found and so on.

This is important when writing software that talk to the ticket server via the [[#API]]. When reading responses from the server the client software can have a default way of handling 404 errors but additionally can have a specific way of handling 404.5 errors.

Where possible, error numbers correspond to the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html HTTP status code definitions]. This is mostly because I'm perverse and think it's funny that when something isn't there you get a 404 error. However, it can be useful when writing your client software in that a 4xx error indicates that the client probably did something wrong whereas 5xx errors indicate that something went wrong on the server (which is potentially much more serious).

==== Source ====

Alphabetically:

===== constants.py =====

Contains various useful constants used in the rest of the XTS source. This makes the code more readable. In the database, the number 2 represents a ticket that is booked. However, instead of using the number 2 to refer to such tickets in the source code, we use the expression <code>ticketstates['BOOKED']</code>. This makes the code (a lot) more readable.

Funnily enough, it's generally a bad idea to change the constants. However, you should add to them where appropriate, for instance, if you intend to record new kinds of events in the log.

''There is nothing technically '''constant''' about the variables in constants.py - they could easily be modified at runtime. If you know how to define constants that are actually constant, or just of a better general approach, then this might be an area of the server that you could improve.''
--[[User:Xander|Xander]] 17:21, 18 July 2008 (BST)

===== data.py =====

data.py provides an interface to the database. Wherever XTS needs to get information from the database, it does it by calling a function in data.py. data.py then takes care of turning the information request into SQL, and if necessary, post-processing the response into a useful form for the caller.

You should be able to port XTS to another datastore simply by replacing data.py.

===== exceptions.py =====

exceptions.py defines the SnewtsError exception type. For more information, see [[#Error_Handling]].

===== helpers.py =====

helpers.py contains various functions that help to solve common and recurring problems in the Snewts application (for instance, turning datetime objects into human-readable date strings). This unclutters [[#logic.py]], which should just contain the business logic of how to sell tickets properly. Functions in helpers.py should ideally be moved into [[#XWF]], but who really cares?

===== logic.py =====

logic.py sits between the client request and the database. When the client asks to sell a ticket, logic.py makes sure that the show actually exists, the ticket is valid for the performance, there are enough tickets left and anything else that needs making sure of. If any one bit of XTS is going to get something critically wrong, it's going to be in logic.py.

logic.py never talks to the database directly. To get data from the database and make changes to the database it must call functions in [[#data.py]].

===== printer.py =====

printer.py is an abstraction layer with one synchronous public function, printTicket(). It takes care of sending the ticket to the [[#Print Server]] and making sure that the printer got the ticket. If the print can't be confirmed it throws a SnewtsError.

===== report.py =====

report.py contains all of the code that formats statistics gathered from the database into XML reports. It also does a little math. See [[#Reporting]].

===== snewts.py =====

snewts.py does the job of recognising requests from clients, checking that the clients are authorised to make the requests, and sending back responses. Simple requests (ie. getPerformances) are fulfilled by getting data from [[#data.py]] directly. More complicated requests are fulfilled by calling business logic in [[#logic.py]] or getting [[#report.py]] to generate reports.

===== status.py =====

status.py contains definitions of all of the errors that XTS may reply with when something goes wrong. If you're writing client software, you need to anticipate these coming back at you.

=== Print Server ===

The print server is a separate entity from the ticketing server that handles ticket printing. It listens on the network for messages instructing it to print tickets.

It is written in pure Java for the convenience of Java's layout and printing library. It uses the effective users' default printer for printing (so this printer needs to be set to the ticket printer).

==== API ====

The print server listens for tickets to print on port . Tickets are sent to the printer as UDP messages on port 8301. The UDP message format consists of six strings terminated by the NULL character. It does not support UTF8 encoding. It is very fail. The strings are, in order:

* Show Name
* Date (expected format: ddd YYYY-MM-DD)
* Time (expected format: HH:MM)
* Booking name (can be an empty string)
* Ticket serial
* Ticket type (ie. "Student")

When the print server receives your ticket and succeeds in dispatching it to the printer it will reply with a UDP packet containing the ticket serial you specified.

==== Making new ticket layouts ====

You need to know Java to write new ticket layouts.

Make a pair of new classes implementing uk.org.opentheatre.xts.Ticket and uk.org.opentheatre.xts.TicketFactory. The former must lay out the ticket, the latter must create instances of the ticket. Look at existing ticket classes for examples on how to do this.

Then, modify the uk.co.bedlamtheatre.BedlamTicketPrintServer to use your new TicketFactory class. You're now done. You can run your modified BedlamTicketPrintServer straight from your IDE and use the taskbar icon that appears to print test tickets and receive tickets from the XTS Ticket Server (if the print service isn't running - see [[#Startup - Windows Services]]). When you're happy with your new layout, replace the classes in C:\XTS\PrinterInterface\bin and either restart the Windows Service or just reboot.

==== Changing the Ticket Logo ====

This is much easier than making a new layout. Just replace C:\Xander\ticketlogo.bmp with your new logo. It should have the same dimensions and should probably be just black and white.

== Making Improvements - a HOWTO ==

=== Getting Started ===

==== Setting Up a Development Server ====

These are the steps I needed to take (and didn't need to take, but that you will need to on other platforms) to set up a development server on a new MacBook on 2008-08-27.

You need to be familiar with Terminal, and you'll be using the sudo command to do things as root. If these things sound frightening you should start by googling around a little.

* Install '''XCode Tools'''. You're going to need XCode so that you can build the Python/MySQL adapter later. You can download XCode from http://developer.apple.com/tools/xcode/. It's free, but it's a big download. While you're downloading it, move onto the next couple of steps.
* '''Python 2.5''' is already installed on Mac OS X 10.5. Rejoice.
* '''easy_install''' is already installed on Mac OS X 10.5. Aren't you glad you bought a Mac?
* Install a '''MySQL database server'''. It's free and open-source. http://dev.mysql.com
* '''Add the MySQL server binaries to your path'''. To do this you need to create a bash profile.
$ sudo emacs .bash_profile
Then, put this in the new file you've just created in EMACS:
export PATH=$PATH:/usr/local/mysql/bin
Then save and close your new profile by pressing CTRL-X, CTRL-S, XTRL-X, CTRL-C. Then to make use of your new profile, close and re-open your terminal.
* So long as the previous step went well you should now be able to '''start up your MySQL server''' by typing:
$ sudo safe_mysqld
If that fails to work, you didn't manage to reconfigure your path properly. Google for help.
* Install '''web.py'''
$ sudo easy_install web.py
* In order to run the administration interface, install '''Django'''. http://www.djangoproject.com/download/
* Build a '''Python/MySQL adapter'''. Download the tarball from http://sourceforge.net/projects/mysql-python. Then untar it, patch _mysql.c by hand and install. Sounds hard? It is. Hopefully by the time you come to do this, installing mysql will be as easy as sudo easy_install mysql_python. See http://forums.mysql.com/read.php?50,175059,219216#msg-219216 for more info.
$ tar -xvf MySQL-python-1.2.2.tar
$ cd MySQL-python-1.2.2
$ emacs _mysql.c (... and patch as shown on teh internets -- you need to comment out lines 37-39)
$ sudo python setup.py install
$ sudo mkdir /usr/local/mysql/lib/mysql
$ sudo cp /usr/local/mysql/lib/libmysqlclient_r.15.dylib /usr/local/mysql/lib/mysql/libmysqlclient_r.15.dylib
You've now finished installing all of the required software. Next you need to set up the initial data and permissions in the database.
* Download '''CocoaMySQL''', or an alternative MySQL client of your choosing.
* '''Log into your own MySQL server''' as root.
* '''Create a database''' called "xts".
* '''Import a database backup''' from Maude. It's the fastest way to get up and running with plenty of real-world data.
* '''Set permissions''' so that the anonymous user on localhost ("@localhost") has full access to the xts database. These are very lax permissions, but they'll do for a development server.

XTS

2008-08-28T15:10:23Z

Xander: /* Setting Up a Development Server */

== eXtensible Ticketing System ==

XTS is the Bedlam Theatre's new ticketing system. It's key feature is extensibility, meaning that if it doesn't do something you want it to do, you (or a suitably inclined geek) should easily be able to add it. Read on for more key features and read further for technical information that will help you maintain and make changes to the system if that is your want.

If you are just looking for help using the software to sell tickets, try [[Using XTS]].

This page is a stub. I intend to document as much of the ticketing system as possible but keep forgetting things that I want to write about. Until it's completed, here's a list of sections that I intend to write under. This article is currently aimed at people who want to maintain the source code, NOT people who want to learn how to sell tickets.

== What I plan to write about ==

* History / Motivation
* Things you should know before you start
** Key Concepts and Terminology
*** "Reserved" vs. "Booked".
*** "Holding" tickets.
*** "Ticket Prototypes"
*** Verifying bookings
*** "Snewts"
*** How XTS handles times between 0AM and 3AM.
** Principles
*** Portability (OS Transparency)
*** Accessibility (Network Transparency)
*** Extensibility
*** Readability
*** Simplicity (Minimum Complexity in the Layers that Matter)
*** High-Level Scripting
* Technologies in use
** HTTP
** XML
** HTML
** CSS
** Python
** Java
* Parts of the system
** DONE Database
*** DONE Scheduled Database Backup
** DONE Ticket Server
*** DONE Web.py
*** DONE API
** DONE Print Server
*** DONE API
*** DONE Making new ticket layouts
*** DONE Changing the ticket logo
** Static Server
*** Apache 2.2
** Administration Server
** Javascript Client
*** Ami
*** Snewts
*** Prism
** Reporting
*** XSLT
** HTTPProxy
*** Protecting the ticketing server from the proxy
** Startup - Windows Services
*** JSWrapper
* Directory Structure (C:\XTS\)
* Installing XTS
* Making Improvements - A HOWTO
** Known Issues / Things you might like to work on
*** Sniffing attacks
*** No test suite, no TDD
*** Transactions (there aren't any)
*** Printing - it's pretty crap
*** Reports - XSLT, but not as it should be
** Familiarisation
*** Grokking the Source
** Tools You Must Use
*** Firebug
*** IPython
** Things You Must Do
*** Setting up your own dev version from trunk
*** Working on a test data set
*** Keeping the documentation up-to-date
** Safe and Unsafe
*** Where is the money?
** Versioning
** Fun Ideas For Improvements or Otherwise
*** Booking from portable devices for producers ("Would you like to come? I'll book you a ticket now.")
*** XTS-controlled DMX for Box Office Lighting Fun Times
*** Heads-up displays for show times and sold out info a-la every cinema you've ever been to

= Documentation =

== Parts of the System ==

=== Database ===

XTS uses a MySQL database. It should be very easy to port XTS to other databases, most access is abstracted through [[#web.py]]'s db module but there may be some report-generating SQL queries that are specific to MySQL in the XTS source. See [[#data.py]] for more info.

The schema is called "xts".

==== Scheduled Database Backups ====

As of 2008-07-18, [[Maude]] is configured to take nightly backups of the XTS database to C:\XTS\Backups. These backups should be scaled back to weeklies or slower at the end of Fringe 2008 or they '''will''' eventually consume all available disk space on the machine. Furthermore the database should occasionally be backed up "off-site" in case of hard disk failure.

=== Ticket Server ===

The ticket server does the hard work of allocating, booking and selling tickets of various types for various performances of various shows. The ticket server is written in [[#Python]]. It is implemented on top of a web server ([http://www.webpy.org web.py]]), allowing clients to interact with the server via [[#HTTP]] using [[#XML]] for data exchange.

The ticket server is accessible via HTTP on port 8080.

==== API ====

API stands for Application Programming Interface. It tells you how you can write programs that talk to the ticket server in order to do useful things (like get show information, or sell tickets online).

The [[#Javascript Client]] uses the XTS API to make a nice box office interface for selling tickets to customers.

If you know a little XML and HTTP you can write programs that interact with the API yourself.

See [[XTS API]] for further information and full documentation.

==== Security ====

The ticket server uses host and password authentication to decide who can do what using the API. Full details are in the [[XTS API|API documentation]].

==== Error Handling ====

When the server encounters an error (for instance, a ticket that you are selling has already been sold), internally it throws a SnewtsError exception.

SnewtsErrors are caught by the request dispatcher (snewtsUrlInvocation in server.py) and turned into an XML-formatted error that is sent back to the client.

SnewtsErrors consist of an error number (useful to computers) and an error message (useful to people). Errors are grouped into types. For instance, all errors that start with the number 404 represent a requested thing not being there ("Not Found"). However, 404.1 specifically means that it was a ticket that wasn't found. 404.2 means a performance wasn't found and so on.

This is important when writing software that talk to the ticket server via the [[#API]]. When reading responses from the server the client software can have a default way of handling 404 errors but additionally can have a specific way of handling 404.5 errors.

Where possible, error numbers correspond to the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html HTTP status code definitions]. This is mostly because I'm perverse and think it's funny that when something isn't there you get a 404 error. However, it can be useful when writing your client software in that a 4xx error indicates that the client probably did something wrong whereas 5xx errors indicate that something went wrong on the server (which is potentially much more serious).

==== Source ====

Alphabetically:

===== constants.py =====

Contains various useful constants used in the rest of the XTS source. This makes the code more readable. In the database, the number 2 represents a ticket that is booked. However, instead of using the number 2 to refer to such tickets in the source code, we use the expression <code>ticketstates['BOOKED']</code>. This makes the code (a lot) more readable.

Funnily enough, it's generally a bad idea to change the constants. However, you should add to them where appropriate, for instance, if you intend to record new kinds of events in the log.

''There is nothing technically '''constant''' about the variables in constants.py - they could easily be modified at runtime. If you know how to define constants that are actually constant, or just of a better general approach, then this might be an area of the server that you could improve.''
--[[User:Xander|Xander]] 17:21, 18 July 2008 (BST)

===== data.py =====

data.py provides an interface to the database. Wherever XTS needs to get information from the database, it does it by calling a function in data.py. data.py then takes care of turning the information request into SQL, and if necessary, post-processing the response into a useful form for the caller.

You should be able to port XTS to another datastore simply by replacing data.py.

===== exceptions.py =====

exceptions.py defines the SnewtsError exception type. For more information, see [[#Error_Handling]].

===== helpers.py =====

helpers.py contains various functions that help to solve common and recurring problems in the Snewts application (for instance, turning datetime objects into human-readable date strings). This unclutters [[#logic.py]], which should just contain the business logic of how to sell tickets properly. Functions in helpers.py should ideally be moved into [[#XWF]], but who really cares?

===== logic.py =====

logic.py sits between the client request and the database. When the client asks to sell a ticket, logic.py makes sure that the show actually exists, the ticket is valid for the performance, there are enough tickets left and anything else that needs making sure of. If any one bit of XTS is going to get something critically wrong, it's going to be in logic.py.

logic.py never talks to the database directly. To get data from the database and make changes to the database it must call functions in [[#data.py]].

===== printer.py =====

printer.py is an abstraction layer with one synchronous public function, printTicket(). It takes care of sending the ticket to the [[#Print Server]] and making sure that the printer got the ticket. If the print can't be confirmed it throws a SnewtsError.

===== report.py =====

report.py contains all of the code that formats statistics gathered from the database into XML reports. It also does a little math. See [[#Reporting]].

===== snewts.py =====

snewts.py does the job of recognising requests from clients, checking that the clients are authorised to make the requests, and sending back responses. Simple requests (ie. getPerformances) are fulfilled by getting data from [[#data.py]] directly. More complicated requests are fulfilled by calling business logic in [[#logic.py]] or getting [[#report.py]] to generate reports.

===== status.py =====

status.py contains definitions of all of the errors that XTS may reply with when something goes wrong. If you're writing client software, you need to anticipate these coming back at you.

=== Print Server ===

The print server is a separate entity from the ticketing server that handles ticket printing. It listens on the network for messages instructing it to print tickets.

It is written in pure Java for the convenience of Java's layout and printing library. It uses the effective users' default printer for printing (so this printer needs to be set to the ticket printer).

==== API ====

The print server listens for tickets to print on port . Tickets are sent to the printer as UDP messages on port 8301. The UDP message format consists of six strings terminated by the NULL character. It does not support UTF8 encoding. It is very fail. The strings are, in order:

* Show Name
* Date (expected format: ddd YYYY-MM-DD)
* Time (expected format: HH:MM)
* Booking name (can be an empty string)
* Ticket serial
* Ticket type (ie. "Student")

When the print server receives your ticket and succeeds in dispatching it to the printer it will reply with a UDP packet containing the ticket serial you specified.

==== Making new ticket layouts ====

You need to know Java to write new ticket layouts.

Make a pair of new classes implementing uk.org.opentheatre.xts.Ticket and uk.org.opentheatre.xts.TicketFactory. The former must lay out the ticket, the latter must create instances of the ticket. Look at existing ticket classes for examples on how to do this.

Then, modify the uk.co.bedlamtheatre.BedlamTicketPrintServer to use your new TicketFactory class. You're now done. You can run your modified BedlamTicketPrintServer straight from your IDE and use the taskbar icon that appears to print test tickets and receive tickets from the XTS Ticket Server (if the print service isn't running - see [[#Startup - Windows Services]]). When you're happy with your new layout, replace the classes in C:\XTS\PrinterInterface\bin and either restart the Windows Service or just reboot.

==== Changing the Ticket Logo ====

This is much easier than making a new layout. Just replace C:\Xander\ticketlogo.bmp with your new logo. It should have the same dimensions and should probably be just black and white.

== Making Improvements - a HOWTO ==

=== Getting Started ===

==== Setting Up a Development Server ====

These are the steps I needed to take (and didn't need to take, but that you will need to on other platforms) to set up a development server on a new MacBook on 2008-08-27.

You need to be familiar with Terminal, and you'll be using the sudo command to do things as root. If these things sound frightening you should start by googling around a little.

* Install '''XCode Tools'''. You're going to need XCode so that you can build the Python/MySQL adapter later. You can download XCode from http://developer.apple.com/tools/xcode/. It's free, but it's a big download. While you're downloading it, move onto the next couple of steps.
* '''Python 2.5''' is already installed on Mac OS X 10.5. Rejoice.
* '''easy_install''' is already installed on Mac OS X 10.5. Aren't you glad you bought a Mac?
* Install a '''MySQL database server'''. It's free and open-source. http://dev.mysql.com
* '''Add the MySQL server binaries to your path'''. To do this you need to create a bash profile.
$ sudo emacs .bash_profile
Then, put this in the new file you've just created in EMACS:
export PATH=$PATH:/usr/local/mysql/bin
Then save and close your new profile by pressing CTRL-X, CTRL-S, XTRL-X, CTRL-C. Then to make use of your new profile, close and re-open your terminal.
* So long as the previous step went well you should now be able to '''start up your MySQL server''' by typing:
$ sudo safe_mysqld
If that fails to work, you didn't manage to reconfigure your path properly. Google for help.
* Install '''web.py'''
$ sudo easy_install web.py
* In order to run the administration interface, install '''Django'''. http://www.djangoproject.com/download/
* Build a '''Python/MySQL adapter'''. Download the tarball from http://sourceforge.net/projects/mysql-python. Then untar it, patch _mysql.c by hand and install. Sounds hard? It is. Hopefully by the time you come to do this, installing mysql will be as easy as sudo easy_install mysql_python. See http://forums.mysql.com/read.php?50,175059,219216#msg-219216 for more info.
$ tar -xvf MySQL-python-1.2.2.tar
$ cd MySQL-python-1.2.2
$ emacs _mysql.c (... and patch as shown on teh internets -- you need to comment out lines 37-39)
$ sudo python setup.py install
$ sudo mkdir /usr/local/mysql/lib/mysql
$ sudo cp /usr/local/mysql/lib/libmysqlclient_r.15.dylib /usr/local/mysql/lib/mysql/libmysqlclient_r.15.dylib

XTS

2008-08-27T16:03:37Z

Xander: /* Setting Up a Development Server */

== eXtensible Ticketing System ==

XTS is the Bedlam Theatre's new ticketing system. It's key feature is extensibility, meaning that if it doesn't do something you want it to do, you (or a suitably inclined geek) should easily be able to add it. Read on for more key features and read further for technical information that will help you maintain and make changes to the system if that is your want.

If you are just looking for help using the software to sell tickets, try [[Using XTS]].

This page is a stub. I intend to document as much of the ticketing system as possible but keep forgetting things that I want to write about. Until it's completed, here's a list of sections that I intend to write under. This article is currently aimed at people who want to maintain the source code, NOT people who want to learn how to sell tickets.

== What I plan to write about ==

* History / Motivation
* Things you should know before you start
** Key Concepts and Terminology
*** "Reserved" vs. "Booked".
*** "Holding" tickets.
*** "Ticket Prototypes"
*** Verifying bookings
*** "Snewts"
*** How XTS handles times between 0AM and 3AM.
** Principles
*** Portability (OS Transparency)
*** Accessibility (Network Transparency)
*** Extensibility
*** Readability
*** Simplicity (Minimum Complexity in the Layers that Matter)
*** High-Level Scripting
* Technologies in use
** HTTP
** XML
** HTML
** CSS
** Python
** Java
* Parts of the system
** DONE Database
*** DONE Scheduled Database Backup
** DONE Ticket Server
*** DONE Web.py
*** DONE API
** DONE Print Server
*** DONE API
*** DONE Making new ticket layouts
*** DONE Changing the ticket logo
** Static Server
*** Apache 2.2
** Administration Server
** Javascript Client
*** Ami
*** Snewts
*** Prism
** Reporting
*** XSLT
** HTTPProxy
*** Protecting the ticketing server from the proxy
** Startup - Windows Services
*** JSWrapper
* Directory Structure (C:\XTS\)
* Installing XTS
* Making Improvements - A HOWTO
** Known Issues / Things you might like to work on
*** Sniffing attacks
*** No test suite, no TDD
*** Transactions (there aren't any)
*** Printing - it's pretty crap
*** Reports - XSLT, but not as it should be
** Familiarisation
*** Grokking the Source
** Tools You Must Use
*** Firebug
*** IPython
** Things You Must Do
*** Setting up your own dev version from trunk
*** Working on a test data set
*** Keeping the documentation up-to-date
** Safe and Unsafe
*** Where is the money?
** Versioning
** Fun Ideas For Improvements or Otherwise
*** Booking from portable devices for producers ("Would you like to come? I'll book you a ticket now.")
*** XTS-controlled DMX for Box Office Lighting Fun Times
*** Heads-up displays for show times and sold out info a-la every cinema you've ever been to

= Documentation =

== Parts of the System ==

=== Database ===

XTS uses a MySQL database. It should be very easy to port XTS to other databases, most access is abstracted through [[#web.py]]'s db module but there may be some report-generating SQL queries that are specific to MySQL in the XTS source. See [[#data.py]] for more info.

The schema is called "xts".

==== Scheduled Database Backups ====

As of 2008-07-18, [[Maude]] is configured to take nightly backups of the XTS database to C:\XTS\Backups. These backups should be scaled back to weeklies or slower at the end of Fringe 2008 or they '''will''' eventually consume all available disk space on the machine. Furthermore the database should occasionally be backed up "off-site" in case of hard disk failure.

=== Ticket Server ===

The ticket server does the hard work of allocating, booking and selling tickets of various types for various performances of various shows. The ticket server is written in [[#Python]]. It is implemented on top of a web server ([http://www.webpy.org web.py]]), allowing clients to interact with the server via [[#HTTP]] using [[#XML]] for data exchange.

The ticket server is accessible via HTTP on port 8080.

==== API ====

API stands for Application Programming Interface. It tells you how you can write programs that talk to the ticket server in order to do useful things (like get show information, or sell tickets online).

The [[#Javascript Client]] uses the XTS API to make a nice box office interface for selling tickets to customers.

If you know a little XML and HTTP you can write programs that interact with the API yourself.

See [[XTS API]] for further information and full documentation.

==== Security ====

The ticket server uses host and password authentication to decide who can do what using the API. Full details are in the [[XTS API|API documentation]].

==== Error Handling ====

When the server encounters an error (for instance, a ticket that you are selling has already been sold), internally it throws a SnewtsError exception.

SnewtsErrors are caught by the request dispatcher (snewtsUrlInvocation in server.py) and turned into an XML-formatted error that is sent back to the client.

SnewtsErrors consist of an error number (useful to computers) and an error message (useful to people). Errors are grouped into types. For instance, all errors that start with the number 404 represent a requested thing not being there ("Not Found"). However, 404.1 specifically means that it was a ticket that wasn't found. 404.2 means a performance wasn't found and so on.

This is important when writing software that talk to the ticket server via the [[#API]]. When reading responses from the server the client software can have a default way of handling 404 errors but additionally can have a specific way of handling 404.5 errors.

Where possible, error numbers correspond to the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html HTTP status code definitions]. This is mostly because I'm perverse and think it's funny that when something isn't there you get a 404 error. However, it can be useful when writing your client software in that a 4xx error indicates that the client probably did something wrong whereas 5xx errors indicate that something went wrong on the server (which is potentially much more serious).

==== Source ====

Alphabetically:

===== constants.py =====

Contains various useful constants used in the rest of the XTS source. This makes the code more readable. In the database, the number 2 represents a ticket that is booked. However, instead of using the number 2 to refer to such tickets in the source code, we use the expression <code>ticketstates['BOOKED']</code>. This makes the code (a lot) more readable.

Funnily enough, it's generally a bad idea to change the constants. However, you should add to them where appropriate, for instance, if you intend to record new kinds of events in the log.

''There is nothing technically '''constant''' about the variables in constants.py - they could easily be modified at runtime. If you know how to define constants that are actually constant, or just of a better general approach, then this might be an area of the server that you could improve.''
--[[User:Xander|Xander]] 17:21, 18 July 2008 (BST)

===== data.py =====

data.py provides an interface to the database. Wherever XTS needs to get information from the database, it does it by calling a function in data.py. data.py then takes care of turning the information request into SQL, and if necessary, post-processing the response into a useful form for the caller.

You should be able to port XTS to another datastore simply by replacing data.py.

===== exceptions.py =====

exceptions.py defines the SnewtsError exception type. For more information, see [[#Error_Handling]].

===== helpers.py =====

helpers.py contains various functions that help to solve common and recurring problems in the Snewts application (for instance, turning datetime objects into human-readable date strings). This unclutters [[#logic.py]], which should just contain the business logic of how to sell tickets properly. Functions in helpers.py should ideally be moved into [[#XWF]], but who really cares?

===== logic.py =====

logic.py sits between the client request and the database. When the client asks to sell a ticket, logic.py makes sure that the show actually exists, the ticket is valid for the performance, there are enough tickets left and anything else that needs making sure of. If any one bit of XTS is going to get something critically wrong, it's going to be in logic.py.

logic.py never talks to the database directly. To get data from the database and make changes to the database it must call functions in [[#data.py]].

===== printer.py =====

printer.py is an abstraction layer with one synchronous public function, printTicket(). It takes care of sending the ticket to the [[#Print Server]] and making sure that the printer got the ticket. If the print can't be confirmed it throws a SnewtsError.

===== report.py =====

report.py contains all of the code that formats statistics gathered from the database into XML reports. It also does a little math. See [[#Reporting]].

===== snewts.py =====

snewts.py does the job of recognising requests from clients, checking that the clients are authorised to make the requests, and sending back responses. Simple requests (ie. getPerformances) are fulfilled by getting data from [[#data.py]] directly. More complicated requests are fulfilled by calling business logic in [[#logic.py]] or getting [[#report.py]] to generate reports.

===== status.py =====

status.py contains definitions of all of the errors that XTS may reply with when something goes wrong. If you're writing client software, you need to anticipate these coming back at you.

=== Print Server ===

The print server is a separate entity from the ticketing server that handles ticket printing. It listens on the network for messages instructing it to print tickets.

It is written in pure Java for the convenience of Java's layout and printing library. It uses the effective users' default printer for printing (so this printer needs to be set to the ticket printer).

==== API ====

The print server listens for tickets to print on port . Tickets are sent to the printer as UDP messages on port 8301. The UDP message format consists of six strings terminated by the NULL character. It does not support UTF8 encoding. It is very fail. The strings are, in order:

* Show Name
* Date (expected format: ddd YYYY-MM-DD)
* Time (expected format: HH:MM)
* Booking name (can be an empty string)
* Ticket serial
* Ticket type (ie. "Student")

When the print server receives your ticket and succeeds in dispatching it to the printer it will reply with a UDP packet containing the ticket serial you specified.

==== Making new ticket layouts ====

You need to know Java to write new ticket layouts.

Make a pair of new classes implementing uk.org.opentheatre.xts.Ticket and uk.org.opentheatre.xts.TicketFactory. The former must lay out the ticket, the latter must create instances of the ticket. Look at existing ticket classes for examples on how to do this.

Then, modify the uk.co.bedlamtheatre.BedlamTicketPrintServer to use your new TicketFactory class. You're now done. You can run your modified BedlamTicketPrintServer straight from your IDE and use the taskbar icon that appears to print test tickets and receive tickets from the XTS Ticket Server (if the print service isn't running - see [[#Startup - Windows Services]]). When you're happy with your new layout, replace the classes in C:\XTS\PrinterInterface\bin and either restart the Windows Service or just reboot.

==== Changing the Ticket Logo ====

This is much easier than making a new layout. Just replace C:\Xander\ticketlogo.bmp with your new logo. It should have the same dimensions and should probably be just black and white.

== Making Improvements - a HOWTO ==

=== Getting Started ===

==== Setting Up a Development Server ====

These are the steps I needed to take (and didn't need to take, but that you will need to on other platforms) to set up a development server on a new MacBook on 2008-08-27.

You need to be familiar with Terminal, and you'll be using the sudo command to do things as root. If these things sound frightening you should start by googling around a little.

* Install '''XCode Tools'''. You're going to need XCode so that you can build the Python/MySQL adapter later. You can download XCode from http://developer.apple.com/tools/xcode/. It's free, but it's a big download. While you're downloading it, move onto the next couple of steps.
* '''Python 2.5''' is already installed on Mac OS X 10.5. Rejoice.
* '''easy_install''' is already installed on Mac OS X 10.5. Aren't you glad you bought a Mac?
* Install a '''MySQL database server'''. It's free and open-source. http://dev.mysql.com
* '''Add the MySQL server binaries to your path'''. To do this you need to create a bash profile.
$ sudo emacs .bash_profile
Then, put this in the new file you've just created in EMACS:
export PATH=$PATH:/usr/local/mysql/bin
Then save and close your new profile by pressing CTRL-X, CTRL-S, XTRL-X, CTRL-C. Then to make use of your new profile, close and re-open your terminal.
* So long as the previous step went well you should now be able to '''start up your MySQL server''' by typing:
$ sudo safe_mysqld
If that fails to work, you didn't manage to reconfigure your path properly. Google for help.
* Install '''web.py'''
$ sudo easy_install web.py
* In order to run the administration interface, install '''Django'''. http://www.djangoproject.com/download/
* Install a '''Python/MySQL adapter'''.
$ sudo easy_install mysql_python

XTS

2008-08-27T15:59:22Z

Xander: /* Setting Up a Development Server */

== eXtensible Ticketing System ==

XTS is the Bedlam Theatre's new ticketing system. It's key feature is extensibility, meaning that if it doesn't do something you want it to do, you (or a suitably inclined geek) should easily be able to add it. Read on for more key features and read further for technical information that will help you maintain and make changes to the system if that is your want.

If you are just looking for help using the software to sell tickets, try [[Using XTS]].

This page is a stub. I intend to document as much of the ticketing system as possible but keep forgetting things that I want to write about. Until it's completed, here's a list of sections that I intend to write under. This article is currently aimed at people who want to maintain the source code, NOT people who want to learn how to sell tickets.

== What I plan to write about ==

* History / Motivation
* Things you should know before you start
** Key Concepts and Terminology
*** "Reserved" vs. "Booked".
*** "Holding" tickets.
*** "Ticket Prototypes"
*** Verifying bookings
*** "Snewts"
*** How XTS handles times between 0AM and 3AM.
** Principles
*** Portability (OS Transparency)
*** Accessibility (Network Transparency)
*** Extensibility
*** Readability
*** Simplicity (Minimum Complexity in the Layers that Matter)
*** High-Level Scripting
* Technologies in use
** HTTP
** XML
** HTML
** CSS
** Python
** Java
* Parts of the system
** DONE Database
*** DONE Scheduled Database Backup
** DONE Ticket Server
*** DONE Web.py
*** DONE API
** DONE Print Server
*** DONE API
*** DONE Making new ticket layouts
*** DONE Changing the ticket logo
** Static Server
*** Apache 2.2
** Administration Server
** Javascript Client
*** Ami
*** Snewts
*** Prism
** Reporting
*** XSLT
** HTTPProxy
*** Protecting the ticketing server from the proxy
** Startup - Windows Services
*** JSWrapper
* Directory Structure (C:\XTS\)
* Installing XTS
* Making Improvements - A HOWTO
** Known Issues / Things you might like to work on
*** Sniffing attacks
*** No test suite, no TDD
*** Transactions (there aren't any)
*** Printing - it's pretty crap
*** Reports - XSLT, but not as it should be
** Familiarisation
*** Grokking the Source
** Tools You Must Use
*** Firebug
*** IPython
** Things You Must Do
*** Setting up your own dev version from trunk
*** Working on a test data set
*** Keeping the documentation up-to-date
** Safe and Unsafe
*** Where is the money?
** Versioning
** Fun Ideas For Improvements or Otherwise
*** Booking from portable devices for producers ("Would you like to come? I'll book you a ticket now.")
*** XTS-controlled DMX for Box Office Lighting Fun Times
*** Heads-up displays for show times and sold out info a-la every cinema you've ever been to

= Documentation =

== Parts of the System ==

=== Database ===

XTS uses a MySQL database. It should be very easy to port XTS to other databases, most access is abstracted through [[#web.py]]'s db module but there may be some report-generating SQL queries that are specific to MySQL in the XTS source. See [[#data.py]] for more info.

The schema is called "xts".

==== Scheduled Database Backups ====

As of 2008-07-18, [[Maude]] is configured to take nightly backups of the XTS database to C:\XTS\Backups. These backups should be scaled back to weeklies or slower at the end of Fringe 2008 or they '''will''' eventually consume all available disk space on the machine. Furthermore the database should occasionally be backed up "off-site" in case of hard disk failure.

=== Ticket Server ===

The ticket server does the hard work of allocating, booking and selling tickets of various types for various performances of various shows. The ticket server is written in [[#Python]]. It is implemented on top of a web server ([http://www.webpy.org web.py]]), allowing clients to interact with the server via [[#HTTP]] using [[#XML]] for data exchange.

The ticket server is accessible via HTTP on port 8080.

==== API ====

API stands for Application Programming Interface. It tells you how you can write programs that talk to the ticket server in order to do useful things (like get show information, or sell tickets online).

The [[#Javascript Client]] uses the XTS API to make a nice box office interface for selling tickets to customers.

If you know a little XML and HTTP you can write programs that interact with the API yourself.

See [[XTS API]] for further information and full documentation.

==== Security ====

The ticket server uses host and password authentication to decide who can do what using the API. Full details are in the [[XTS API|API documentation]].

==== Error Handling ====

When the server encounters an error (for instance, a ticket that you are selling has already been sold), internally it throws a SnewtsError exception.

SnewtsErrors are caught by the request dispatcher (snewtsUrlInvocation in server.py) and turned into an XML-formatted error that is sent back to the client.

SnewtsErrors consist of an error number (useful to computers) and an error message (useful to people). Errors are grouped into types. For instance, all errors that start with the number 404 represent a requested thing not being there ("Not Found"). However, 404.1 specifically means that it was a ticket that wasn't found. 404.2 means a performance wasn't found and so on.

This is important when writing software that talk to the ticket server via the [[#API]]. When reading responses from the server the client software can have a default way of handling 404 errors but additionally can have a specific way of handling 404.5 errors.

Where possible, error numbers correspond to the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html HTTP status code definitions]. This is mostly because I'm perverse and think it's funny that when something isn't there you get a 404 error. However, it can be useful when writing your client software in that a 4xx error indicates that the client probably did something wrong whereas 5xx errors indicate that something went wrong on the server (which is potentially much more serious).

==== Source ====

Alphabetically:

===== constants.py =====

Contains various useful constants used in the rest of the XTS source. This makes the code more readable. In the database, the number 2 represents a ticket that is booked. However, instead of using the number 2 to refer to such tickets in the source code, we use the expression <code>ticketstates['BOOKED']</code>. This makes the code (a lot) more readable.

Funnily enough, it's generally a bad idea to change the constants. However, you should add to them where appropriate, for instance, if you intend to record new kinds of events in the log.

''There is nothing technically '''constant''' about the variables in constants.py - they could easily be modified at runtime. If you know how to define constants that are actually constant, or just of a better general approach, then this might be an area of the server that you could improve.''
--[[User:Xander|Xander]] 17:21, 18 July 2008 (BST)

===== data.py =====

data.py provides an interface to the database. Wherever XTS needs to get information from the database, it does it by calling a function in data.py. data.py then takes care of turning the information request into SQL, and if necessary, post-processing the response into a useful form for the caller.

You should be able to port XTS to another datastore simply by replacing data.py.

===== exceptions.py =====

exceptions.py defines the SnewtsError exception type. For more information, see [[#Error_Handling]].

===== helpers.py =====

helpers.py contains various functions that help to solve common and recurring problems in the Snewts application (for instance, turning datetime objects into human-readable date strings). This unclutters [[#logic.py]], which should just contain the business logic of how to sell tickets properly. Functions in helpers.py should ideally be moved into [[#XWF]], but who really cares?

===== logic.py =====

logic.py sits between the client request and the database. When the client asks to sell a ticket, logic.py makes sure that the show actually exists, the ticket is valid for the performance, there are enough tickets left and anything else that needs making sure of. If any one bit of XTS is going to get something critically wrong, it's going to be in logic.py.

logic.py never talks to the database directly. To get data from the database and make changes to the database it must call functions in [[#data.py]].

===== printer.py =====

printer.py is an abstraction layer with one synchronous public function, printTicket(). It takes care of sending the ticket to the [[#Print Server]] and making sure that the printer got the ticket. If the print can't be confirmed it throws a SnewtsError.

===== report.py =====

report.py contains all of the code that formats statistics gathered from the database into XML reports. It also does a little math. See [[#Reporting]].

===== snewts.py =====

snewts.py does the job of recognising requests from clients, checking that the clients are authorised to make the requests, and sending back responses. Simple requests (ie. getPerformances) are fulfilled by getting data from [[#data.py]] directly. More complicated requests are fulfilled by calling business logic in [[#logic.py]] or getting [[#report.py]] to generate reports.

===== status.py =====

status.py contains definitions of all of the errors that XTS may reply with when something goes wrong. If you're writing client software, you need to anticipate these coming back at you.

=== Print Server ===

The print server is a separate entity from the ticketing server that handles ticket printing. It listens on the network for messages instructing it to print tickets.

It is written in pure Java for the convenience of Java's layout and printing library. It uses the effective users' default printer for printing (so this printer needs to be set to the ticket printer).

==== API ====

The print server listens for tickets to print on port . Tickets are sent to the printer as UDP messages on port 8301. The UDP message format consists of six strings terminated by the NULL character. It does not support UTF8 encoding. It is very fail. The strings are, in order:

* Show Name
* Date (expected format: ddd YYYY-MM-DD)
* Time (expected format: HH:MM)
* Booking name (can be an empty string)
* Ticket serial
* Ticket type (ie. "Student")

When the print server receives your ticket and succeeds in dispatching it to the printer it will reply with a UDP packet containing the ticket serial you specified.

==== Making new ticket layouts ====

You need to know Java to write new ticket layouts.

Make a pair of new classes implementing uk.org.opentheatre.xts.Ticket and uk.org.opentheatre.xts.TicketFactory. The former must lay out the ticket, the latter must create instances of the ticket. Look at existing ticket classes for examples on how to do this.

Then, modify the uk.co.bedlamtheatre.BedlamTicketPrintServer to use your new TicketFactory class. You're now done. You can run your modified BedlamTicketPrintServer straight from your IDE and use the taskbar icon that appears to print test tickets and receive tickets from the XTS Ticket Server (if the print service isn't running - see [[#Startup - Windows Services]]). When you're happy with your new layout, replace the classes in C:\XTS\PrinterInterface\bin and either restart the Windows Service or just reboot.

==== Changing the Ticket Logo ====

This is much easier than making a new layout. Just replace C:\Xander\ticketlogo.bmp with your new logo. It should have the same dimensions and should probably be just black and white.

== Making Improvements - a HOWTO ==

=== Getting Started ===

==== Setting Up a Development Server ====

These are the steps I needed to take (and didn't need to take, but that you will need to on other platforms) to set up a development server on a new MacBook on 2008-08-27.

You need to be familiar with Terminal, and you'll be using the sudo command to do things as root. If these things sound frightening you should start by googling around a little.

* Install '''XCode Tools'''. You're going to need XCode so that you can build the Python/MySQL adapter later. You can download XCode from http://developer.apple.com/tools/xcode/. It's free, but it's a big download. While you're downloading it, move onto the next couple of steps.
* '''Python 2.5''' is already installed on Mac OS X 10.5. Rejoice.
* '''easy_install''' is already installed on Mac OS X 10.5. Aren't you glad you bought a Mac?
* Install a '''MySQL database server'''. It's free and open-source. http://dev.mysql.com
* '''Add the MySQL server binaries to your path'''. To do this you need to create a bash profile.
$ sudo emacs .bash_profile
Then, put this in the new file you've just created in EMACS:
export PATH=$PATH:/usr/local/mysql/bin
Then save and close your new profile by pressing CTRL-X, CTRL-S, XTRL-X, CTRL-C. Then to make use of your new profile, close and re-open your terminal.
* So long as the previous step went well you should now be able to '''start up your MySQL server''' by typing:
$ sudo safe_mysqld
If that fails to work, you didn't manage to reconfigure your path properly. Google for help.
* Install '''web.py'''
$ sudo easy_install web.py
* In order to run the administration interface, install '''Django'''. http://www.djangoproject.com/documentation/install/
* Install a '''Python/MySQL adapter'''.
$ sudo easy_install mysql_python

XTS

2008-08-27T15:56:05Z

Xander: /* Setting Up a Development Server */

== eXtensible Ticketing System ==

XTS is the Bedlam Theatre's new ticketing system. It's key feature is extensibility, meaning that if it doesn't do something you want it to do, you (or a suitably inclined geek) should easily be able to add it. Read on for more key features and read further for technical information that will help you maintain and make changes to the system if that is your want.

If you are just looking for help using the software to sell tickets, try [[Using XTS]].

This page is a stub. I intend to document as much of the ticketing system as possible but keep forgetting things that I want to write about. Until it's completed, here's a list of sections that I intend to write under. This article is currently aimed at people who want to maintain the source code, NOT people who want to learn how to sell tickets.

== What I plan to write about ==

* History / Motivation
* Things you should know before you start
** Key Concepts and Terminology
*** "Reserved" vs. "Booked".
*** "Holding" tickets.
*** "Ticket Prototypes"
*** Verifying bookings
*** "Snewts"
*** How XTS handles times between 0AM and 3AM.
** Principles
*** Portability (OS Transparency)
*** Accessibility (Network Transparency)
*** Extensibility
*** Readability
*** Simplicity (Minimum Complexity in the Layers that Matter)
*** High-Level Scripting
* Technologies in use
** HTTP
** XML
** HTML
** CSS
** Python
** Java
* Parts of the system
** DONE Database
*** DONE Scheduled Database Backup
** DONE Ticket Server
*** DONE Web.py
*** DONE API
** DONE Print Server
*** DONE API
*** DONE Making new ticket layouts
*** DONE Changing the ticket logo
** Static Server
*** Apache 2.2
** Administration Server
** Javascript Client
*** Ami
*** Snewts
*** Prism
** Reporting
*** XSLT
** HTTPProxy
*** Protecting the ticketing server from the proxy
** Startup - Windows Services
*** JSWrapper
* Directory Structure (C:\XTS\)
* Installing XTS
* Making Improvements - A HOWTO
** Known Issues / Things you might like to work on
*** Sniffing attacks
*** No test suite, no TDD
*** Transactions (there aren't any)
*** Printing - it's pretty crap
*** Reports - XSLT, but not as it should be
** Familiarisation
*** Grokking the Source
** Tools You Must Use
*** Firebug
*** IPython
** Things You Must Do
*** Setting up your own dev version from trunk
*** Working on a test data set
*** Keeping the documentation up-to-date
** Safe and Unsafe
*** Where is the money?
** Versioning
** Fun Ideas For Improvements or Otherwise
*** Booking from portable devices for producers ("Would you like to come? I'll book you a ticket now.")
*** XTS-controlled DMX for Box Office Lighting Fun Times
*** Heads-up displays for show times and sold out info a-la every cinema you've ever been to

= Documentation =

== Parts of the System ==

=== Database ===

XTS uses a MySQL database. It should be very easy to port XTS to other databases, most access is abstracted through [[#web.py]]'s db module but there may be some report-generating SQL queries that are specific to MySQL in the XTS source. See [[#data.py]] for more info.

The schema is called "xts".

==== Scheduled Database Backups ====

As of 2008-07-18, [[Maude]] is configured to take nightly backups of the XTS database to C:\XTS\Backups. These backups should be scaled back to weeklies or slower at the end of Fringe 2008 or they '''will''' eventually consume all available disk space on the machine. Furthermore the database should occasionally be backed up "off-site" in case of hard disk failure.

=== Ticket Server ===

The ticket server does the hard work of allocating, booking and selling tickets of various types for various performances of various shows. The ticket server is written in [[#Python]]. It is implemented on top of a web server ([http://www.webpy.org web.py]]), allowing clients to interact with the server via [[#HTTP]] using [[#XML]] for data exchange.

The ticket server is accessible via HTTP on port 8080.

==== API ====

API stands for Application Programming Interface. It tells you how you can write programs that talk to the ticket server in order to do useful things (like get show information, or sell tickets online).

The [[#Javascript Client]] uses the XTS API to make a nice box office interface for selling tickets to customers.

If you know a little XML and HTTP you can write programs that interact with the API yourself.

See [[XTS API]] for further information and full documentation.

==== Security ====

The ticket server uses host and password authentication to decide who can do what using the API. Full details are in the [[XTS API|API documentation]].

==== Error Handling ====

When the server encounters an error (for instance, a ticket that you are selling has already been sold), internally it throws a SnewtsError exception.

SnewtsErrors are caught by the request dispatcher (snewtsUrlInvocation in server.py) and turned into an XML-formatted error that is sent back to the client.

SnewtsErrors consist of an error number (useful to computers) and an error message (useful to people). Errors are grouped into types. For instance, all errors that start with the number 404 represent a requested thing not being there ("Not Found"). However, 404.1 specifically means that it was a ticket that wasn't found. 404.2 means a performance wasn't found and so on.

This is important when writing software that talk to the ticket server via the [[#API]]. When reading responses from the server the client software can have a default way of handling 404 errors but additionally can have a specific way of handling 404.5 errors.

Where possible, error numbers correspond to the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html HTTP status code definitions]. This is mostly because I'm perverse and think it's funny that when something isn't there you get a 404 error. However, it can be useful when writing your client software in that a 4xx error indicates that the client probably did something wrong whereas 5xx errors indicate that something went wrong on the server (which is potentially much more serious).

==== Source ====

Alphabetically:

===== constants.py =====

Contains various useful constants used in the rest of the XTS source. This makes the code more readable. In the database, the number 2 represents a ticket that is booked. However, instead of using the number 2 to refer to such tickets in the source code, we use the expression <code>ticketstates['BOOKED']</code>. This makes the code (a lot) more readable.

Funnily enough, it's generally a bad idea to change the constants. However, you should add to them where appropriate, for instance, if you intend to record new kinds of events in the log.

''There is nothing technically '''constant''' about the variables in constants.py - they could easily be modified at runtime. If you know how to define constants that are actually constant, or just of a better general approach, then this might be an area of the server that you could improve.''
--[[User:Xander|Xander]] 17:21, 18 July 2008 (BST)

===== data.py =====

data.py provides an interface to the database. Wherever XTS needs to get information from the database, it does it by calling a function in data.py. data.py then takes care of turning the information request into SQL, and if necessary, post-processing the response into a useful form for the caller.

You should be able to port XTS to another datastore simply by replacing data.py.

===== exceptions.py =====

exceptions.py defines the SnewtsError exception type. For more information, see [[#Error_Handling]].

===== helpers.py =====

helpers.py contains various functions that help to solve common and recurring problems in the Snewts application (for instance, turning datetime objects into human-readable date strings). This unclutters [[#logic.py]], which should just contain the business logic of how to sell tickets properly. Functions in helpers.py should ideally be moved into [[#XWF]], but who really cares?

===== logic.py =====

logic.py sits between the client request and the database. When the client asks to sell a ticket, logic.py makes sure that the show actually exists, the ticket is valid for the performance, there are enough tickets left and anything else that needs making sure of. If any one bit of XTS is going to get something critically wrong, it's going to be in logic.py.

logic.py never talks to the database directly. To get data from the database and make changes to the database it must call functions in [[#data.py]].

===== printer.py =====

printer.py is an abstraction layer with one synchronous public function, printTicket(). It takes care of sending the ticket to the [[#Print Server]] and making sure that the printer got the ticket. If the print can't be confirmed it throws a SnewtsError.

===== report.py =====

report.py contains all of the code that formats statistics gathered from the database into XML reports. It also does a little math. See [[#Reporting]].

===== snewts.py =====

snewts.py does the job of recognising requests from clients, checking that the clients are authorised to make the requests, and sending back responses. Simple requests (ie. getPerformances) are fulfilled by getting data from [[#data.py]] directly. More complicated requests are fulfilled by calling business logic in [[#logic.py]] or getting [[#report.py]] to generate reports.

===== status.py =====

status.py contains definitions of all of the errors that XTS may reply with when something goes wrong. If you're writing client software, you need to anticipate these coming back at you.

=== Print Server ===

The print server is a separate entity from the ticketing server that handles ticket printing. It listens on the network for messages instructing it to print tickets.

It is written in pure Java for the convenience of Java's layout and printing library. It uses the effective users' default printer for printing (so this printer needs to be set to the ticket printer).

==== API ====

The print server listens for tickets to print on port . Tickets are sent to the printer as UDP messages on port 8301. The UDP message format consists of six strings terminated by the NULL character. It does not support UTF8 encoding. It is very fail. The strings are, in order:

* Show Name
* Date (expected format: ddd YYYY-MM-DD)
* Time (expected format: HH:MM)
* Booking name (can be an empty string)
* Ticket serial
* Ticket type (ie. "Student")

When the print server receives your ticket and succeeds in dispatching it to the printer it will reply with a UDP packet containing the ticket serial you specified.

==== Making new ticket layouts ====

You need to know Java to write new ticket layouts.

Make a pair of new classes implementing uk.org.opentheatre.xts.Ticket and uk.org.opentheatre.xts.TicketFactory. The former must lay out the ticket, the latter must create instances of the ticket. Look at existing ticket classes for examples on how to do this.

Then, modify the uk.co.bedlamtheatre.BedlamTicketPrintServer to use your new TicketFactory class. You're now done. You can run your modified BedlamTicketPrintServer straight from your IDE and use the taskbar icon that appears to print test tickets and receive tickets from the XTS Ticket Server (if the print service isn't running - see [[#Startup - Windows Services]]). When you're happy with your new layout, replace the classes in C:\XTS\PrinterInterface\bin and either restart the Windows Service or just reboot.

==== Changing the Ticket Logo ====

This is much easier than making a new layout. Just replace C:\Xander\ticketlogo.bmp with your new logo. It should have the same dimensions and should probably be just black and white.

== Making Improvements - a HOWTO ==

=== Getting Started ===

==== Setting Up a Development Server ====

These are the steps I needed to take (and didn't need to take, but that you will need to on other platforms) to set up a development server on a new MacBook on 2008-08-27.

You need to be familiar with Terminal, and you'll be using the sudo command to do things as root. If these things sound frightening you should start by googling around a little.

* Install '''XCode Tools'''. You're going to need XCode so that you can build the Python/MySQL adapter later. You can download XCode from http://developer.apple.com/tools/xcode/. It's free, but it's a big download. While you're downloading it, move onto the next couple of steps.
* '''Python 2.5''' is already installed on Mac OS X 10.5. Rejoice.
* '''easy_install''' is already installed on Mac OS X 10.5. Aren't you glad you bought a Mac?
* Install a '''MySQL database server'''. It's free and open-source. http://dev.mysql.com
* '''Add the MySQL server binaries to your path'''. To do this you need to create a bash profile.
$ sudo emacs .bash_profile
Then, put this in the new file you've just created in EMACS:
export PATH=$PATH:/usr/local/mysql/bin
Then save and close your new profile by pressing CTRL-X, CTRL-S, XTRL-X, CTRL-C. Then to make use of your new profile, close and re-open your terminal.
* So long as the previous step went well you should now be able to '''start up your MySQL server''' by typing:
$ sudo safe_mysqld
If that fails to work, you didn't manage to reconfigure your path properly. Google for help.
* Install a '''Python/MySQL adapter'''.
$ sudo easy_install mysql_python

XTS

2008-08-27T15:34:37Z

Xander: /* Setting Up a Development Server */

== eXtensible Ticketing System ==

XTS is the Bedlam Theatre's new ticketing system. It's key feature is extensibility, meaning that if it doesn't do something you want it to do, you (or a suitably inclined geek) should easily be able to add it. Read on for more key features and read further for technical information that will help you maintain and make changes to the system if that is your want.

If you are just looking for help using the software to sell tickets, try [[Using XTS]].

This page is a stub. I intend to document as much of the ticketing system as possible but keep forgetting things that I want to write about. Until it's completed, here's a list of sections that I intend to write under. This article is currently aimed at people who want to maintain the source code, NOT people who want to learn how to sell tickets.

== What I plan to write about ==

* History / Motivation
* Things you should know before you start
** Key Concepts and Terminology
*** "Reserved" vs. "Booked".
*** "Holding" tickets.
*** "Ticket Prototypes"
*** Verifying bookings
*** "Snewts"
*** How XTS handles times between 0AM and 3AM.
** Principles
*** Portability (OS Transparency)
*** Accessibility (Network Transparency)
*** Extensibility
*** Readability
*** Simplicity (Minimum Complexity in the Layers that Matter)
*** High-Level Scripting
* Technologies in use
** HTTP
** XML
** HTML
** CSS
** Python
** Java
* Parts of the system
** DONE Database
*** DONE Scheduled Database Backup
** DONE Ticket Server
*** DONE Web.py
*** DONE API
** DONE Print Server
*** DONE API
*** DONE Making new ticket layouts
*** DONE Changing the ticket logo
** Static Server
*** Apache 2.2
** Administration Server
** Javascript Client
*** Ami
*** Snewts
*** Prism
** Reporting
*** XSLT
** HTTPProxy
*** Protecting the ticketing server from the proxy
** Startup - Windows Services
*** JSWrapper
* Directory Structure (C:\XTS\)
* Installing XTS
* Making Improvements - A HOWTO
** Known Issues / Things you might like to work on
*** Sniffing attacks
*** No test suite, no TDD
*** Transactions (there aren't any)
*** Printing - it's pretty crap
*** Reports - XSLT, but not as it should be
** Familiarisation
*** Grokking the Source
** Tools You Must Use
*** Firebug
*** IPython
** Things You Must Do
*** Setting up your own dev version from trunk
*** Working on a test data set
*** Keeping the documentation up-to-date
** Safe and Unsafe
*** Where is the money?
** Versioning
** Fun Ideas For Improvements or Otherwise
*** Booking from portable devices for producers ("Would you like to come? I'll book you a ticket now.")
*** XTS-controlled DMX for Box Office Lighting Fun Times
*** Heads-up displays for show times and sold out info a-la every cinema you've ever been to

= Documentation =

== Parts of the System ==

=== Database ===

XTS uses a MySQL database. It should be very easy to port XTS to other databases, most access is abstracted through [[#web.py]]'s db module but there may be some report-generating SQL queries that are specific to MySQL in the XTS source. See [[#data.py]] for more info.

The schema is called "xts".

==== Scheduled Database Backups ====

As of 2008-07-18, [[Maude]] is configured to take nightly backups of the XTS database to C:\XTS\Backups. These backups should be scaled back to weeklies or slower at the end of Fringe 2008 or they '''will''' eventually consume all available disk space on the machine. Furthermore the database should occasionally be backed up "off-site" in case of hard disk failure.

=== Ticket Server ===

The ticket server does the hard work of allocating, booking and selling tickets of various types for various performances of various shows. The ticket server is written in [[#Python]]. It is implemented on top of a web server ([http://www.webpy.org web.py]]), allowing clients to interact with the server via [[#HTTP]] using [[#XML]] for data exchange.

The ticket server is accessible via HTTP on port 8080.

==== API ====

API stands for Application Programming Interface. It tells you how you can write programs that talk to the ticket server in order to do useful things (like get show information, or sell tickets online).

The [[#Javascript Client]] uses the XTS API to make a nice box office interface for selling tickets to customers.

If you know a little XML and HTTP you can write programs that interact with the API yourself.

See [[XTS API]] for further information and full documentation.

==== Security ====

The ticket server uses host and password authentication to decide who can do what using the API. Full details are in the [[XTS API|API documentation]].

==== Error Handling ====

When the server encounters an error (for instance, a ticket that you are selling has already been sold), internally it throws a SnewtsError exception.

SnewtsErrors are caught by the request dispatcher (snewtsUrlInvocation in server.py) and turned into an XML-formatted error that is sent back to the client.

SnewtsErrors consist of an error number (useful to computers) and an error message (useful to people). Errors are grouped into types. For instance, all errors that start with the number 404 represent a requested thing not being there ("Not Found"). However, 404.1 specifically means that it was a ticket that wasn't found. 404.2 means a performance wasn't found and so on.

This is important when writing software that talk to the ticket server via the [[#API]]. When reading responses from the server the client software can have a default way of handling 404 errors but additionally can have a specific way of handling 404.5 errors.

Where possible, error numbers correspond to the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html HTTP status code definitions]. This is mostly because I'm perverse and think it's funny that when something isn't there you get a 404 error. However, it can be useful when writing your client software in that a 4xx error indicates that the client probably did something wrong whereas 5xx errors indicate that something went wrong on the server (which is potentially much more serious).

==== Source ====

Alphabetically:

===== constants.py =====

Contains various useful constants used in the rest of the XTS source. This makes the code more readable. In the database, the number 2 represents a ticket that is booked. However, instead of using the number 2 to refer to such tickets in the source code, we use the expression <code>ticketstates['BOOKED']</code>. This makes the code (a lot) more readable.

Funnily enough, it's generally a bad idea to change the constants. However, you should add to them where appropriate, for instance, if you intend to record new kinds of events in the log.

''There is nothing technically '''constant''' about the variables in constants.py - they could easily be modified at runtime. If you know how to define constants that are actually constant, or just of a better general approach, then this might be an area of the server that you could improve.''
--[[User:Xander|Xander]] 17:21, 18 July 2008 (BST)

===== data.py =====

data.py provides an interface to the database. Wherever XTS needs to get information from the database, it does it by calling a function in data.py. data.py then takes care of turning the information request into SQL, and if necessary, post-processing the response into a useful form for the caller.

You should be able to port XTS to another datastore simply by replacing data.py.

===== exceptions.py =====

exceptions.py defines the SnewtsError exception type. For more information, see [[#Error_Handling]].

===== helpers.py =====

helpers.py contains various functions that help to solve common and recurring problems in the Snewts application (for instance, turning datetime objects into human-readable date strings). This unclutters [[#logic.py]], which should just contain the business logic of how to sell tickets properly. Functions in helpers.py should ideally be moved into [[#XWF]], but who really cares?

===== logic.py =====

logic.py sits between the client request and the database. When the client asks to sell a ticket, logic.py makes sure that the show actually exists, the ticket is valid for the performance, there are enough tickets left and anything else that needs making sure of. If any one bit of XTS is going to get something critically wrong, it's going to be in logic.py.

logic.py never talks to the database directly. To get data from the database and make changes to the database it must call functions in [[#data.py]].

===== printer.py =====

printer.py is an abstraction layer with one synchronous public function, printTicket(). It takes care of sending the ticket to the [[#Print Server]] and making sure that the printer got the ticket. If the print can't be confirmed it throws a SnewtsError.

===== report.py =====

report.py contains all of the code that formats statistics gathered from the database into XML reports. It also does a little math. See [[#Reporting]].

===== snewts.py =====

snewts.py does the job of recognising requests from clients, checking that the clients are authorised to make the requests, and sending back responses. Simple requests (ie. getPerformances) are fulfilled by getting data from [[#data.py]] directly. More complicated requests are fulfilled by calling business logic in [[#logic.py]] or getting [[#report.py]] to generate reports.

===== status.py =====

status.py contains definitions of all of the errors that XTS may reply with when something goes wrong. If you're writing client software, you need to anticipate these coming back at you.

=== Print Server ===

The print server is a separate entity from the ticketing server that handles ticket printing. It listens on the network for messages instructing it to print tickets.

It is written in pure Java for the convenience of Java's layout and printing library. It uses the effective users' default printer for printing (so this printer needs to be set to the ticket printer).

==== API ====

The print server listens for tickets to print on port . Tickets are sent to the printer as UDP messages on port 8301. The UDP message format consists of six strings terminated by the NULL character. It does not support UTF8 encoding. It is very fail. The strings are, in order:

* Show Name
* Date (expected format: ddd YYYY-MM-DD)
* Time (expected format: HH:MM)
* Booking name (can be an empty string)
* Ticket serial
* Ticket type (ie. "Student")

When the print server receives your ticket and succeeds in dispatching it to the printer it will reply with a UDP packet containing the ticket serial you specified.

==== Making new ticket layouts ====

You need to know Java to write new ticket layouts.

Make a pair of new classes implementing uk.org.opentheatre.xts.Ticket and uk.org.opentheatre.xts.TicketFactory. The former must lay out the ticket, the latter must create instances of the ticket. Look at existing ticket classes for examples on how to do this.

Then, modify the uk.co.bedlamtheatre.BedlamTicketPrintServer to use your new TicketFactory class. You're now done. You can run your modified BedlamTicketPrintServer straight from your IDE and use the taskbar icon that appears to print test tickets and receive tickets from the XTS Ticket Server (if the print service isn't running - see [[#Startup - Windows Services]]). When you're happy with your new layout, replace the classes in C:\XTS\PrinterInterface\bin and either restart the Windows Service or just reboot.

==== Changing the Ticket Logo ====

This is much easier than making a new layout. Just replace C:\Xander\ticketlogo.bmp with your new logo. It should have the same dimensions and should probably be just black and white.

== Making Improvements - a HOWTO ==

=== Getting Started ===

==== Setting Up a Development Server ====

These are the steps I needed to take (and didn't need to take, but that you will need to on other platforms) to set up a development server on a new MacBook on 2008-08-27.

You need to be familiar with Terminal, and you'll be using the sudo command to do things as root. If these things sound frightening you should start by googling around a little.

* Install XCode Tools. You're going to need XCode so that you can build the Python/MySQL adapter later. You can download XCode from http://developer.apple.com/tools/xcode/. It's free, but it's a big download. While you're downloading it, move onto the next couple of steps.
* '''Python 2.5''' is already installed on Mac OS X 10.5. Rejoice.
* '''easy_install''' is already installed on Mac OS X 10.5. Aren't you glad you bought a Mac?
* Install a '''MySQL database server'''. It's free and open-source. http://dev.mysql.com
* '''Add the MySQL server binaries to your path'''. To do this you need to create a bash profile.
$ sudo emacs .bash_profile
Then, put this in the new file you've just created in EMACS:
export PATH=$PATH:/usr/local/mysql/bin
Then save and close your new profile by pressing CTRL-X, CTRL-S, XTRL-X, CTRL-C. Then to make use of your new profile, close and re-open your terminal.
* So long as the previous step went well you should now be able to '''start up your MySQL server''' by typing:
$ sudo safe_mysqld
If that fails to work, you didn't manage to reconfigure your path properly. Google for help.
* Install a '''Python/MySQL adapter'''.
$ sudo easy_install mysql_python

XTS

2008-08-27T15:33:40Z

Xander: /* Setting Up a Development Server */

== eXtensible Ticketing System ==

XTS is the Bedlam Theatre's new ticketing system. It's key feature is extensibility, meaning that if it doesn't do something you want it to do, you (or a suitably inclined geek) should easily be able to add it. Read on for more key features and read further for technical information that will help you maintain and make changes to the system if that is your want.

If you are just looking for help using the software to sell tickets, try [[Using XTS]].

This page is a stub. I intend to document as much of the ticketing system as possible but keep forgetting things that I want to write about. Until it's completed, here's a list of sections that I intend to write under. This article is currently aimed at people who want to maintain the source code, NOT people who want to learn how to sell tickets.

== What I plan to write about ==

* History / Motivation
* Things you should know before you start
** Key Concepts and Terminology
*** "Reserved" vs. "Booked".
*** "Holding" tickets.
*** "Ticket Prototypes"
*** Verifying bookings
*** "Snewts"
*** How XTS handles times between 0AM and 3AM.
** Principles
*** Portability (OS Transparency)
*** Accessibility (Network Transparency)
*** Extensibility
*** Readability
*** Simplicity (Minimum Complexity in the Layers that Matter)
*** High-Level Scripting
* Technologies in use
** HTTP
** XML
** HTML
** CSS
** Python
** Java
* Parts of the system
** DONE Database
*** DONE Scheduled Database Backup
** DONE Ticket Server
*** DONE Web.py
*** DONE API
** DONE Print Server
*** DONE API
*** DONE Making new ticket layouts
*** DONE Changing the ticket logo
** Static Server
*** Apache 2.2
** Administration Server
** Javascript Client
*** Ami
*** Snewts
*** Prism
** Reporting
*** XSLT
** HTTPProxy
*** Protecting the ticketing server from the proxy
** Startup - Windows Services
*** JSWrapper
* Directory Structure (C:\XTS\)
* Installing XTS
* Making Improvements - A HOWTO
** Known Issues / Things you might like to work on
*** Sniffing attacks
*** No test suite, no TDD
*** Transactions (there aren't any)
*** Printing - it's pretty crap
*** Reports - XSLT, but not as it should be
** Familiarisation
*** Grokking the Source
** Tools You Must Use
*** Firebug
*** IPython
** Things You Must Do
*** Setting up your own dev version from trunk
*** Working on a test data set
*** Keeping the documentation up-to-date
** Safe and Unsafe
*** Where is the money?
** Versioning
** Fun Ideas For Improvements or Otherwise
*** Booking from portable devices for producers ("Would you like to come? I'll book you a ticket now.")
*** XTS-controlled DMX for Box Office Lighting Fun Times
*** Heads-up displays for show times and sold out info a-la every cinema you've ever been to

= Documentation =

== Parts of the System ==

=== Database ===

XTS uses a MySQL database. It should be very easy to port XTS to other databases, most access is abstracted through [[#web.py]]'s db module but there may be some report-generating SQL queries that are specific to MySQL in the XTS source. See [[#data.py]] for more info.

The schema is called "xts".

==== Scheduled Database Backups ====

As of 2008-07-18, [[Maude]] is configured to take nightly backups of the XTS database to C:\XTS\Backups. These backups should be scaled back to weeklies or slower at the end of Fringe 2008 or they '''will''' eventually consume all available disk space on the machine. Furthermore the database should occasionally be backed up "off-site" in case of hard disk failure.

=== Ticket Server ===

The ticket server does the hard work of allocating, booking and selling tickets of various types for various performances of various shows. The ticket server is written in [[#Python]]. It is implemented on top of a web server ([http://www.webpy.org web.py]]), allowing clients to interact with the server via [[#HTTP]] using [[#XML]] for data exchange.

The ticket server is accessible via HTTP on port 8080.

==== API ====

API stands for Application Programming Interface. It tells you how you can write programs that talk to the ticket server in order to do useful things (like get show information, or sell tickets online).

The [[#Javascript Client]] uses the XTS API to make a nice box office interface for selling tickets to customers.

If you know a little XML and HTTP you can write programs that interact with the API yourself.

See [[XTS API]] for further information and full documentation.

==== Security ====

The ticket server uses host and password authentication to decide who can do what using the API. Full details are in the [[XTS API|API documentation]].

==== Error Handling ====

When the server encounters an error (for instance, a ticket that you are selling has already been sold), internally it throws a SnewtsError exception.

SnewtsErrors are caught by the request dispatcher (snewtsUrlInvocation in server.py) and turned into an XML-formatted error that is sent back to the client.

SnewtsErrors consist of an error number (useful to computers) and an error message (useful to people). Errors are grouped into types. For instance, all errors that start with the number 404 represent a requested thing not being there ("Not Found"). However, 404.1 specifically means that it was a ticket that wasn't found. 404.2 means a performance wasn't found and so on.

This is important when writing software that talk to the ticket server via the [[#API]]. When reading responses from the server the client software can have a default way of handling 404 errors but additionally can have a specific way of handling 404.5 errors.

Where possible, error numbers correspond to the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html HTTP status code definitions]. This is mostly because I'm perverse and think it's funny that when something isn't there you get a 404 error. However, it can be useful when writing your client software in that a 4xx error indicates that the client probably did something wrong whereas 5xx errors indicate that something went wrong on the server (which is potentially much more serious).

==== Source ====

Alphabetically:

===== constants.py =====

Contains various useful constants used in the rest of the XTS source. This makes the code more readable. In the database, the number 2 represents a ticket that is booked. However, instead of using the number 2 to refer to such tickets in the source code, we use the expression <code>ticketstates['BOOKED']</code>. This makes the code (a lot) more readable.

Funnily enough, it's generally a bad idea to change the constants. However, you should add to them where appropriate, for instance, if you intend to record new kinds of events in the log.

''There is nothing technically '''constant''' about the variables in constants.py - they could easily be modified at runtime. If you know how to define constants that are actually constant, or just of a better general approach, then this might be an area of the server that you could improve.''
--[[User:Xander|Xander]] 17:21, 18 July 2008 (BST)

===== data.py =====

data.py provides an interface to the database. Wherever XTS needs to get information from the database, it does it by calling a function in data.py. data.py then takes care of turning the information request into SQL, and if necessary, post-processing the response into a useful form for the caller.

You should be able to port XTS to another datastore simply by replacing data.py.

===== exceptions.py =====

exceptions.py defines the SnewtsError exception type. For more information, see [[#Error_Handling]].

===== helpers.py =====

helpers.py contains various functions that help to solve common and recurring problems in the Snewts application (for instance, turning datetime objects into human-readable date strings). This unclutters [[#logic.py]], which should just contain the business logic of how to sell tickets properly. Functions in helpers.py should ideally be moved into [[#XWF]], but who really cares?

===== logic.py =====

logic.py sits between the client request and the database. When the client asks to sell a ticket, logic.py makes sure that the show actually exists, the ticket is valid for the performance, there are enough tickets left and anything else that needs making sure of. If any one bit of XTS is going to get something critically wrong, it's going to be in logic.py.

logic.py never talks to the database directly. To get data from the database and make changes to the database it must call functions in [[#data.py]].

===== printer.py =====

printer.py is an abstraction layer with one synchronous public function, printTicket(). It takes care of sending the ticket to the [[#Print Server]] and making sure that the printer got the ticket. If the print can't be confirmed it throws a SnewtsError.

===== report.py =====

report.py contains all of the code that formats statistics gathered from the database into XML reports. It also does a little math. See [[#Reporting]].

===== snewts.py =====

snewts.py does the job of recognising requests from clients, checking that the clients are authorised to make the requests, and sending back responses. Simple requests (ie. getPerformances) are fulfilled by getting data from [[#data.py]] directly. More complicated requests are fulfilled by calling business logic in [[#logic.py]] or getting [[#report.py]] to generate reports.

===== status.py =====

status.py contains definitions of all of the errors that XTS may reply with when something goes wrong. If you're writing client software, you need to anticipate these coming back at you.

=== Print Server ===

The print server is a separate entity from the ticketing server that handles ticket printing. It listens on the network for messages instructing it to print tickets.

It is written in pure Java for the convenience of Java's layout and printing library. It uses the effective users' default printer for printing (so this printer needs to be set to the ticket printer).

==== API ====

The print server listens for tickets to print on port . Tickets are sent to the printer as UDP messages on port 8301. The UDP message format consists of six strings terminated by the NULL character. It does not support UTF8 encoding. It is very fail. The strings are, in order:

* Show Name
* Date (expected format: ddd YYYY-MM-DD)
* Time (expected format: HH:MM)
* Booking name (can be an empty string)
* Ticket serial
* Ticket type (ie. "Student")

When the print server receives your ticket and succeeds in dispatching it to the printer it will reply with a UDP packet containing the ticket serial you specified.

==== Making new ticket layouts ====

You need to know Java to write new ticket layouts.

Make a pair of new classes implementing uk.org.opentheatre.xts.Ticket and uk.org.opentheatre.xts.TicketFactory. The former must lay out the ticket, the latter must create instances of the ticket. Look at existing ticket classes for examples on how to do this.

Then, modify the uk.co.bedlamtheatre.BedlamTicketPrintServer to use your new TicketFactory class. You're now done. You can run your modified BedlamTicketPrintServer straight from your IDE and use the taskbar icon that appears to print test tickets and receive tickets from the XTS Ticket Server (if the print service isn't running - see [[#Startup - Windows Services]]). When you're happy with your new layout, replace the classes in C:\XTS\PrinterInterface\bin and either restart the Windows Service or just reboot.

==== Changing the Ticket Logo ====

This is much easier than making a new layout. Just replace C:\Xander\ticketlogo.bmp with your new logo. It should have the same dimensions and should probably be just black and white.

== Making Improvements - a HOWTO ==

=== Getting Started ===

==== Setting Up a Development Server ====

These are the steps I needed to take (and didn't need to take, but that you will need to on other platforms) to set up a development server on a new MacBook on 2008-08-27.

You need to be familiar with Terminal, and you'll be using the sudo command to do things as root. If these things sound frightening you should start by googling around a little.

* Install XCode Tools. You're going to need XCode so that you can build the Python/MySQL adapter later. You can download XCode from http://developer.apple.com/tools/xcode/. It's free, but it's a big download. While you're downloading it, move onto the next couple of steps.
* '''Python 2.5''' is already installed on Mac OS X 10.5. Rejoice.
* '''easy_install''' is already installed on Mac OS X 10.5. Aren't you glad you bought a Mac?
* Install a '''MySQL database server'''. It's free and open-source. http://dev.mysql.com
* Add the MySQL server binaries to your path. To do this you need to create a bash profile.
$ sudo emacs .bash_profile
Then, put this in the new file you've just created in EMACS:
export PATH=$PATH:/usr/local/mysql/bin
Then save and close your new profile by pressing CTRL-X, CTRL-S, XTRL-X, CTRL-C. Then to make use of your new profile, close and re-open your terminal.
* So long as the previous step went well you should now be able to start up your MySQL server by typing:
$ sudo safe_mysqld
If that fails to work, you didn't manage to reconfigure your path properly. Google for help.
* Install a Python/MySQL adapter.
$ sudo easy_install mysql_python

XTS

2008-08-27T15:12:49Z

Xander: /* Documentation */ Adding a set-up section

XTS

2008-08-10T20:34:35Z

Xander: /* What I plan to write about */

XTS

2008-07-26T17:04:12Z

Xander: /* Ticket Server */

XTS

2008-07-26T17:03:19Z

Xander: /* What I plan to write about */

XTS

2008-07-26T17:02:46Z

Xander: /* Parts of the System */ Documented the Print Server

XTS

2008-07-26T16:35:58Z

Xander: /* printer.py */

XTS

2008-07-26T16:34:49Z

Xander: /* printer.py */

XTS

2008-07-26T16:27:15Z

Xander: /* What I plan to write about */

XTS

2008-07-26T16:24:57Z

Xander: /* What I plan to write about */

XTS

2008-07-26T16:24:19Z

Xander: /* eXtensible Ticketing System */

XTS

2008-07-26T16:24:01Z

Xander: /* eXtensible Ticketing System */

XTS

2008-07-26T16:23:46Z

Xander: /* eXtensible Ticketing System */

== eXtensible Ticketing System ==

XTS is the Bedlam Theatre's new ticketing system. It's key feature is extensibility, meaning that if it doesn't do something you want it to do you (or a suitably inclined geek) should easily be able to add it. Read on for key features and read further for technical information that will help you maintain and make changes to the system if that is your want.

If you are just looking for help using the software to sell tickets, try [[Using XTS]].

This page is a stub. I intend to document as much of the ticketing system as possible but keep forgetting things that I want to write about. Until it's completed, here's a list of sections that I intend to write under. This article is currently aimed at people who want to maintain the source code, NOT people who want to learn how to sell tickets.

== What I plan to write about ==

* History / Motivation
* Things you should know before you start
** Key Concepts and Terminology
*** "Reserved" vs. "Booked".
*** "Holding" tickets.
*** "Ticket Prototypes"
*** "Snewts"
*** How XTS handles times between 0AM and 3AM.
** Principles
*** Portability (OS Transparency)
*** Accessibility (Network Transparency)
*** Extensibility
*** Readability
*** Simplicity (Minimum Complexity in the Layers that Matter)
*** High-Level Scripting
* Technologies in use
** HTTP
** XML
** HTML
** CSS
** Python
** Java
* Parts of the system
** Database
*** Scheduled Database Backup
** DONE Ticket Server
*** DONE Web.py
*** DONE API
** Print Server
*** API
*** Making new ticket layouts
*** Changing the ticket logo
** Static Server
*** Apache 2.2
** Administration Server
** Javascript Client
*** Ami
*** Snewts
*** Prism
** Reporting
*** XSLT
** HTTPProxy
*** Protecting the ticketing server from the proxy
** Startup - Windows Services
*** JSWrapper
* Directory Structure (C:\XTS\)
* Installing XTS
* Making Improvements - A HOWTO
** Known Issues / Things you might like to work on
*** Sniffing attacks
*** No test suite, no TDD
*** Transactions (there aren't any)
*** Printing - it's pretty crap
*** Reports - XSLT, but not as it should be
** Familiarisation
*** Grokking the Source
** Tools You Must Use
*** Firebug
*** IPython
** Things You Must Do
*** Setting up your own dev version from trunk
*** Working on a test data set
*** Keeping the documentation up-to-date
** Safe and Unsafe
*** Where is the money?
** Versioning

= Documentation =

== Parts of the System ==

=== Database ===

XTS uses a MySQL database. It should be very easy to port XTS to other databases, most access is abstracted through [[#web.py]]'s db module but there may be some report-generating SQL queries that are specific to MySQL in the XTS source. See [[#data.py]] for more info.

The schema is called "xts".

==== Scheduled Database Backups ====

As of 2008-07-18, [[Maude]] is configured to take nightly backups of the XTS database to C:\XTS\Backups. These backups should be scaled back to weeklies or slower at the end of Fringe 2008 or they '''will''' eventually consume all available disk space on the machine. Furthermore the database should occasionally be backed up "off-site" in case of hard disk failure.

=== Ticket Server ===

The ticket server does the hard work of allocating, booking and selling tickets of various types for various performances of various shows. The ticket server is written in [[#Python]]. It is implemented on top of a web server ([http://www.webpy.org web.py]]), allowing clients to interact with the server via [[#HTTP]] using [[#XML]] for data exchange.

==== API ====

API stands for Application Programming Interface. It tells you how you can write programs that talk to the ticket server in order to do useful things (like get show information, or sell tickets online).

The [[#Javascript Client]] uses the XTS API to make a nice box office interface for selling tickets to customers.

If you know a little XML and HTTP you can write programs that interact with the API yourself.

See [[XTS API]] for further information and full documentation.

==== Security ====

The ticket server uses host and password authentication to decide who can do what using the API. Full details are in the [[XTS API|API documentation]].

==== Error Handling ====

When the server encounters an error (for instance, a ticket that you are selling has already been sold), internally it throws a SnewtsError exception.

SnewtsErrors are caught by the request dispatcher (snewtsUrlInvocation in server.py) and turned into an XML-formatted error that is sent back to the client.

SnewtsErrors consist of an error number (useful to computers) and an error message (useful to people). Errors are grouped into types. For instance, all errors that start with the number 404 represent a requested thing not being there ("Not Found"). However, 404.1 specifically means that it was a ticket that wasn't found. 404.2 means a performance wasn't found and so on.

This is important when writing software that talk to the ticket server via the [[#API]]. When reading responses from the server the client software can have a default way of handling 404 errors but additionally can have a specific way of handling 404.5 errors.

Where possible, error numbers correspond to the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html HTTP status code definitions]. This is mostly because I'm perverse and think it's funny that when something isn't there you get a 404 error. However, it can be useful when writing your client software in that a 4xx error indicates that the client probably did something wrong whereas 5xx errors indicate that something went wrong on the server (which is potentially much more serious).

==== Source ====

Alphabetically:

===== constants.py =====

Contains various useful constants used in the rest of the XTS source. This makes the code more readable. In the database, the number 2 represents a ticket that is booked. However, instead of using the number 2 to refer to such tickets in the source code, we use the expression <code>ticketstates['BOOKED']</code>. This makes the code (a lot) more readable.

Funnily enough, it's generally a bad idea to change the constants. However, you should add to them where appropriate, for instance, if you intend to record new kinds of events in the log.

''There is nothing technically '''constant''' about the variables in constants.py - they could easily be modified at runtime. If you know how to define constants that are actually constant, or just of a better general approach, then this might be an area of the server that you could improve.''
--[[User:Xander|Xander]] 17:21, 18 July 2008 (BST)

===== data.py =====

data.py provides an interface to the database. Wherever XTS needs to get information from the database, it does it by calling a function in data.py. data.py then takes care of turning the information request into SQL, and if necessary, post-processing the response into a useful form for the caller.

You should be able to port XTS to another datastore simply by replacing data.py.

===== exceptions.py =====

exceptions.py defines the SnewtsError exception type. For more information, see [[#Error_Handling]].

===== helpers.py =====

helpers.py contains various functions that help to solve common and recurring problems in the Snewts application (for instance, turning datetime objects into human-readable date strings). This unclutters [[#logic.py]], which should just contain the business logic of how to sell tickets properly. Functions in helpers.py should ideally be moved into [[#XWF]], but who really cares?

===== logic.py =====

logic.py sits between the client request and the database. When the client asks to sell a ticket, logic.py makes sure that the show actually exists, the ticket is valid for the performance, there are enough tickets left and anything else that needs making sure of. If any one bit of XTS is going to get something critically wrong, it's going to be in logic.py.

logic.py never talks to the database directly. To get data from the database and make changes to the database it must call functions in [[#data.py]].

===== printer.py =====

printer.py is an abstraction layer with one synchronous public function, printTicket(). It takes care of sending the ticket to the printer and making sure that the printer got the ticket. If the print can't be confirmed it throws a SnewtsError.

===== report.py =====

report.py contains all of the code that formats statistics gathered from the database into XML reports. It also does a little math. See [[#Reporting]].

===== snewts.py =====

snewts.py does the job of recognising requests from clients, checking that the clients are authorised to make the requests, and sending back responses. Simple requests (ie. getPerformances) are fulfilled by getting data from [[#data.py]] directly. More complicated requests are fulfilled by calling business logic in [[#logic.py]] or getting [[#report.py]] to generate reports.

===== status.py =====

status.py contains definitions of all of the errors that XTS may reply with when something goes wrong. If you're writing client software, you need to anticipate these coming back at you.

Main Page

2008-07-26T16:17:54Z

Xander: /* How do I sign up? */ Tweaked for encouragement.

[[Image:IMGP0219.jpg|thumb|350px|The Bedlam Theatre]]Welcome to the Bedlam Wiki. It is hoped that this will become a valuable resource for all [[EUTC]] and Bedlam Theatre matters.

===How does it work?===

Basically this is an online resource which is editable by anybody that has registered.

Simply click EDIT at the top of the screen to edit an article.

If an article doesn't exist then you can create it - simply search for an article - if it doesn't already exist you will be invited to create it! Easy!

Here are a few links to look at...

* [[A to Z]]
* [[How To]]
* [[Guide to Building|Building Guide]]
* [[Special:Allpages|All Pages]]
* [[Special:Categories|Categories]]

===How do I sign up?===

Signing up has been disabled due to spammers but we still want your contributions. Please email [http://www.thatscottishengineer.co.uk Alistair] or one of the [[EUTC Wiki:Administrators|other admins]] (including the [[Secretary]] and [[Tech manager]]) your full name and the user name you want.

----

===Disclamer===

Please be aware that this online community does not speak for, or on behalf of the [[Edinburgh University Theatre Company]] or individuals with current, previous or past responsibility or any of current, previous, past or [[life members]]. Any comments contained within are purely those of the author and not of the company or of any individual.

There is no restriction nor moderation on this wiki - if you see a mistake, please correct it. If you see something inappropriate / libellous then please remove it.

'''Have you got any suggestions? Email [mailto:webmaster@bedlamtheatre.co.uk the webmaster] or [http://www.thatscottishengineer.co.uk Alistair]'''

Bedlam Fringe

2008-07-26T16:15:23Z

Xander: /* Fringe 2008 */

Every August the Bedlam turns professional and opens up as Fringe Venue 49.

Here's a history of the people involved...

==Fringe 2008==

*Fringe Venue Manager: Colleen Patterson
*Theatre Manager: Mal Mead
*Technical Manager: Sam Hansford
*Press and Publicity Manager: Becs Kamp
*Business Manager: Fran Walker
*Graphics Designer: Nick Kay
*Box Office Managers: Lauren McLeod and Xander Macmillan
*Cafe Managers: Cat Hobart and Ellie Harrison
*Box Office Staff: Liz Black, Dylan Read, Fred Gordon, Emma Pattinson, Ellie Richardson, Nicola Hazelton, Lucy Sneddon, Maredith Close
*Cafe Staff: Amy Brewer, Alex Hatt, Carley Stubbs, Emily Jenkinson

Achievements:


*Repainted [[office]] and redid [[committee]] pigeonholes
*New Sunday opening times on sunday afternoons with pub quiz and café entertainment


*Installed new [[seats]]
*Renovated and refinished the seating rake
*Laid new carpet in the auditorium
*Reskinned the [[stage]] (we totally do this every year)
*Re-finished the stage's risers with 18mm plywood
*Spray-painted the [[rig]] black for stealth
*Moved the [[lighting store]] to the dimmers


*Rebuilt the [[cafe]] servery
*Partially restored and re-varnished cafe floor
*Rebuilt cafe boards
*Fixed the bulge in the [[cafe]] wall


*Rewrote the [[XTS|ticketing system]]
*Fixed the [[FOH Sound|FoH Sound System]]
*Installed a lighting bar in the box office, bought a Bedlam Theatre logo gobo for projection.

==Fringe 2007==

*Fringe Venue Manager: Matt Wieteska
*Theatre Manager: Colleen Patterson
*Technical Manager: Neale Dutton
*Press and Publicity Manager: Lucy Jackson
*Graphics Designer: Nick Kay
*Sponsorship Manager: Becs Kamp
*Box Office Managers: Alex Hall and Mike Smith
*Cafe Managers: James "Bruce" Sinclair and Holly Mclay
*Box Office Staff: Lauren McLeod, Kate Wieteska, Felix Trench, Reg Scott, Chloe Edworthy, Mairi Kellock, Cat Hoyle, Becs Kamp
*Cafe Staff: Lauren Fried, Becca Day-Preston, Chris Cotter, Craig Hamilton

'''Achievements:'''

*Built a wall in the [[auditorium]] to help with soundproofing
*Reskinned the [[stage]]
*New [[box office]] printer
*Installed [[sound]] system

==Fringe 2006==

*Fringe Venue Manager: Charlotte Jarvis
*Theatre Manager: Alex Engel
*Technical Manager: Matt Wieteska
*Press and Publicity Manager: Simon Hodges
*Graphics Designer: Chris Mounsey
*Box Office Managers: Helena Larkin and Tom Latter
*Café Managers: Clemmie Cooke and Charlotte Coles
*Box Office Staff: Cat Hoyle, James Turner Inman, Richard Shore, Katy Bartholomew, Colleen Patterson, Natalia Prochnicka and Geraldine Heaney
*Cafe Staff:

'''Achievements:'''

*Replaced blackout [[curtains]] on [[balcony]] with new black fabric
*New coffee machine with fancy coffee capabilities for [[cafe]]
*Built large schedule chalkboards for outside
*Painted [[office]] white and blue
*Reskinned the [[stage]]

==Fringe 2005==

*Fringe Venue Manager: Claire Glendenning
*Theatre Manager: James Turner-Inman
*Technical Manager: Paul Foxcroft
*Press and Publicity Manager: Andrew Nielson
*Graphics Designer: Chris Mounsey
*Box Office Managers: Heather Hanshaw + Nick Bustin
*Café Managers: Graeme Wright + Becca Davis
*Box Office Staff: Jeremy Bidgood, Rob Stott, Rosie Drew, Alex Engel, Charlotte Jarvis
*Cafe Staff: Emma Drage,

'''Achievements:'''

*Replaced carpet in [[auditorium]] with carpet tiles
*New freezer
*Improved [[box office]] system with thermal ticket printer and new software
*Re-hung rig (termtime budget?)
*Created trus-based awning for front of building (sponsored by Becks)
*Installed ADSL [[internet connection]], network cabling and wireless network
*Loads of painting
*Improved soundproofing in between [[café]] and [[auditorium]] around the door
*Pimped up the [[office]]
*New storage solutions in [[techbox]] and [[balcony]] for screws and stuff
*Various new bits and bobs for the [[café]] e.g. tea light lanterns
*Purchase of Dog (who is a rabbit) [and is very cute]
*Re-skinned [[stage]]
*Sanded down and varnished [[cafe]] floor

==Fringe 2004==

*Fringe Venue Manager: Miriam Raines
*Theatre Manager:
*Technical Manager: James Turner-Inman
*Press and Publicity Manager:
*Graphics Designer:
*Box Office Managers: Paul Foxcroft, Martin Cavanagh
*Café Managers:
*Box Office Staff:
*Cafe Staff:

==Fringe 2003==

*Fringe Venue Manager: Cat Smith
*Theatre Manager: Jono Ellis
*Technical Manager: Matt Ling
*Press and Publicity Manager: Sarah Cook
*Graphics Designer/Website: Neil E. Hobbs
*Box Office Managers: Alison Timms and Kirsten Morris
*Café Managers: Victoria Tills and Kati Hind
*Box Office Staff:
*Cafe Staff:
 
'''Achievements:''' 
*New potato oven and chiller cabinet for [[cafe]]
*New [[sound]] system - two speakers, mini disc players, new MC2 amp, graphics - paid for by profit from Fringe 2002 (!)
*New level in [[costume cupboard]] - see graffiti!
*Skinned [[stage cupboard]] for the first time and removed wall and rail allowing it to become a stage pit
*Redid [[cafe]] and [[toilets]]
*Installed fan in [[cafe]] to improve ventilation
*Obtained two microwaves
*Redid [[kitchen]] - repainted and tiled walls, obtained new oven and hobs
*Cut down number of [[EUTC]] slots to two
*Held first [[FOB]] [[A_to_Z#AGM_-_Annual_General_Meeting|AGM]]
*Held first full preview week schedule
*Held art exhibition in collabaration with ECA
*Bought picnic table to extend [[cafe]] area (buy a new one!)
*Made more money than Graeme Timms (sorry long standing debate!)

==Fringe 2002==

*Fringe Venue Manager: Graeme Timms
*Theatre Manager: Richard Hogg
*Technical Manager: Matt Gray
*Press and Publicity Manager: Neil E. Hobbs
*Graphics Designer/Website: Neil E. Hobbs
*Box Office Managers: Pete Lowden and Sarah Kerr
*Café Managers: Cat Smith and Rachel Mountfield
*Box Office Staff:
*Cafe Staff:
 
'''Achievements:''' 
*Replaced damaged floorboards on [[stage]] during re-skinning
*Dug out back passage and laid path and red chips round that side of building
*Re-built [[box office]] counter
*Installed Tramp-Cam
*Much re-wiring of light fittings and sockets
*Computerised the [[Box office]] ticketing system
*Built the Info-Cat - (He never quite became a cat)
*Replaced lighting in [[toilets]]
*Rebranded '''Bedlam Fringe''' as a separate entity from term-time operation
*First website with up-to-date reviews, show info, etc
*Much painting
*Consumption of the more Caley Golden Promise that the Cash and Carry could stock!!

FOH Sound

2008-07-26T16:05:57Z

Xander: Added backstage feed information (currently not connected)

= Front Of House Sound System =

Front Of House sound is distributed from a Zone Mixer in the Box Office, secured to the underside of the shelf immediately to the left of the Box Office computer.

The Zone Mixer takes up to six inputs and sends sound to three zones. Each zone can be independently set to play back one of the six inputs.

As of 2008-07-26 the mappings are:

=== Inputs ===
* Input 1: Unassigned
* Input 2: Box Office CD player
* Input 3: Box Office Minijack (for iPods, laptops, etc)
* Input 4: Unassigned
* Input 5: Unassigned
* Input 6: Tech Box Feed

=== Zones ===
* Zone 1: Café
* Zone 2: Box Office
* Zone 3: Toilet Corridor

= Maintenance =

== Mono/Stereo ==

The café is the only zone that has stereo playback - this is a limitation of the Zone Mixer. Additionally, the tech box feed is mono so all playback from the tech box is strictly mono. However, sound from other sources will be in stereo in the café.

== Tech Box Feed ==

The tech box feed enters the box office via a cable on the right side of the box office cupboard door frame.

== Backstage Feed ==

As of 2008-07-26 there is cabling for a backstage feed but it is not connected as a zone (we instead are using this zone for the toilet corridor). The backstage feed is potentially useful as a stage monitor for actors in the dressing room, so if this suits you you may like to find the dangling connector pair hidden behind the amps and sub out a zone on the mixer in order to reconnect it.

The backstage feed is wired with cat5e (purple sheath) carrying both mono sound and the signal wires for the zone remote.

== Remotes ==

Any zone can be controlled remotely by attaching a (wall-mounted) remote. When the zone is controlled remotely the first two knobs for the zone (input select and volume) no longer have any effect on the mixer (having been overridden by the knobs on the remote). As of 2008-07-26, only the café zone is controlled by a remote, on the left wall of the café when facing out. This makes it easier for box office staff to keep the box office and toilet corridor playing from the same input.

== Amplifiers ==

Each zone has a separate amplifier, all amplifiers are stacked on the floor beneath the zone mixer. The toilet corridor amp is only driving one speaker, this is ideal because the other channel on the amplifier does not work. You make want to take this into account if repurposing the amps.

Don't change the gains on the amplifiers, use the zone volume knobs instead.

As with the tech box sound system, turn on the zone mixer before turning on the amplifiers. When powering down, turn off the amplifiers before turning off the zone mixer.

== Adding more inputs ==

The back of the zone mixer is readily accessible by sticking your head into the shelf space and having a strong light source to hand. The inputs are at the right end of the back of the device (or your left, once you've stuck your head in the shelf). Input one is the edgemost, input six is nearest the middle.

Make sure any wires you add are cabletied neatly so that the shelf space beneath the zone mixer is still as usable as possible. Additionally, keep the next person to come along happy by labelling your cables at both ends. You will be loved.

== Doing more interesting stuff with the Zone Mixer ==

If you need to mess with the zone mappings, remotes, zone EQs or other more advanced stuff you should unscrew the zone mixer from its brackets and get a better look - the device is completely self-documented in astonishingly detail by diagrams on the top and the bottom of the case - including required wiring configurations for the connectors and other useful stuff to know.

FOH Sound

2008-07-26T16:01:21Z

Xander: /* Front Of House Sound System */ Proofing

= Front Of House Sound System =

Front Of House sound is distributed from a Zone Mixer in the Box Office, secured to the underside of the shelf immediately to the left of the Box Office computer.

The Zone Mixer takes up to six inputs and sends sound to three zones. Each zone can be independently set to play back one of the six inputs.

As of 2008-07-26 the mappings are:

=== Inputs ===
* Input 1: Unassigned
* Input 2: Box Office CD player
* Input 3: Box Office Minijack (for iPods, laptops, etc)
* Input 4: Unassigned
* Input 5: Unassigned
* Input 6: Tech Box Feed

=== Zones ===
* Zone 1: Café
* Zone 2: Box Office
* Zone 3: Toilet Corridor

= Maintenance =

== Mono/Stereo ==

The café is the only zone that has stereo playback - this is a limitation of the Zone Mixer. Additionally, the tech box feed is mono so all playback from the tech box is strictly mono. However, sound from other sources will be in stereo in the café.

== Tech Box Feed ==

The tech box feed enters the box office via a cable on the right side of the box office cupboard door frame.

== Remotes ==

Any zone can be controlled remotely by attaching a (wall-mounted) remote. When the zone is controlled remotely the first two knobs for the zone (input select and volume) no longer have any effect on the mixer (having been overridden by the knobs on the remote). As of 2008-07-26, only the café zone is controlled by a remote, on the left wall of the café when facing out. This makes it easier for box office staff to keep the box office and toilet corridor playing from the same input.

== Amplifiers ==

Each zone has a separate amplifier, all amplifiers are stacked on the floor beneath the zone mixer. The toilet corridor amp is only driving one speaker, this is ideal because the other channel on the amplifier does not work. You make want to take this into account if repurposing the amps.

Don't change the gains on the amplifiers, use the zone volume knobs instead.

As with the tech box sound system, turn on the zone mixer before turning on the amplifiers. When powering down, turn off the amplifiers before turning off the zone mixer.

== Adding more inputs ==

The back of the zone mixer is readily accessible by sticking your head into the shelf space and having a strong light source to hand. The inputs are at the right end of the back of the device (or your left, once you've stuck your head in the shelf). Input one is the edgemost, input six is nearest the middle.

Make sure any wires you add are cabletied neatly so that the shelf space beneath the zone mixer is still as usable as possible. Additionally, keep the next person to come along happy by labelling your cables at both ends. You will be loved.

== Doing more interesting stuff with the Zone Mixer ==

If you need to mess with the zone mappings, remotes, zone EQs or other more advanced stuff you should unscrew the zone mixer from its brackets and get a better look - the device is completely self-documented in astonishingly detail by diagrams on the top and the bottom of the case - including required wiring configurations for the connectors and other useful stuff to know.

FOH Sound

2008-07-26T15:57:20Z

Xander: Configuration and maintenance info for the Front of House sound system

= Front Of House Sound System =

Front Of House sound is distributed from a Zone Mixer in the Box Office, secured to the underside of the shelf immediately to the left of the Box Office computer.

The Zone Mixer takes up to six inputs and sends sound to three zones. Each zone can be independently set to play back one of the six inputs.

As of 2008-07-26 the mappings are:

- Input 1: Unassigned
- Input 2: Box Office CD player
- Input 3: Box Office Minijack (for iPods, laptops, etc)
- Input 4: Unassigned
- Input 5: Unassigned
- Input 6: Tech Box Feed

- Zone 1: Café
- Zone 2: Box Office
- Zone 3: Toilet Corridor

== Mono/Stereo ==

The café is the only zone that has stereo playback - this is a limitation of the Zone Mixer. Additionally, the tech box feed is mono so all playback from the tech box is strictly mono. However, sound from other sources will be in stereo in the café.

== Tech Box Feed ==

The tech box feed enters the box office via a cable on the right side of the box office cupboard door frame.

== Remotes ==

Any zone can be controlled remotely by attaching a (wall-mounted) remote. When the zone is controlled remotely the first two knobs for the zone (input select and volume) no longer have any effect on the mixer (being overridden by the knobs on the remote). As of 2008-07-26, only the café zone is controlled by a remote, on the left wall of the café when facing out. This makes it easier for box office staff to keep the box office and toilet corridor playing from the same input.

== Amplifiers ==

Each zone needs a separate amplifier, all amplifiers are stacked on the floor beneath the zone mixer. The toilet corridor amp is only driving one speaker, this is ideal because the other channel on the amplifier does not work. You make want to take this into account if repurposing the amps.

Don't change the gains on the amplifiers, use the zone volume knobs instead.

As with the tech box sound system, turn on the zone mixer before turning on the amplifiers. When powering down, turn off the amplifiers before turning off the zone mixer.

== Adding more inputs ==

The back of the zone mixer is readily accessible by sticking your head into the shelf space and having a strong light source to hand. The inputs are at the right end of the back of the device (or your left, once you've stuck your head in the shelf). Input one is the edgemost, input six is nearest the middle.

Make sure any wires you add are cabletied neatly so that the shelf space beneath the zone mixer is still as usable as possible. Additionally, keep the next person to come along happy by labelling your cables at both ends. You will be loved.

== Doing more interesting stuff with the Zone Mixer ==

If you need to mess with the zone mappings, remotes, zone EQs or other more advanced stuff you should unscrew the zone mixer from it's brackets and get a better look - the device is completely self-documented by astonishingly detailed diagrams on the top and the bottom of the case - including required wiring configurations for the connectors and other useful stuff to know.

Bedlam Fringe

2008-07-26T15:38:36Z

Xander: /* Fringe 2008 */

Every August the Bedlam turns professional and opens up as Fringe Venue 49.

Here's a history of the people involved...

==Fringe 2008==

*Fringe Venue Manager: Colleen Patterson
*Theatre Manager: Mal Mead
*Technical Manager: Sam Hansford
*Press and Publicity Manager: Becs Kamp
*Business Manager: Fran Walker
*Graphics Designer: Nick Kay
*Box Office Managers: Lauren McLeod and Xander Macmillan
*Cafe Managers: Cat Hobart and Ellie Harrison
*Box Office Staff: Liz Black, Dylan Read, Fred Gordon, Emma Pattinson, Ellie Richardson, Nicola Hazelton, Lucy Sneddon, Maredith Close
*Cafe Staff: Amy Brewer, Alex Hatt, Carley Stubbs, Emily Jenkinson

Achievements:

Auditorium: installed new [[seats]], renovated and refinished the rake, laid new carpet 
Renovation of [[cafe]] servery 
Repainted [[office]] and redid [[committee]] pigeonholes 
Reskinned the [[stage]] 
Re-finished the stage's risers with 18mm plywood 
New Sunday opening times, Sunday afternoons 
Spray painted the [[rig]] black 
Fixed the bulge in the [[cafe]] wall 
Moved the [[lighting store]] 
Partially restored and re-varnished cafe floor 
Rebuilt cafe boards 
Threw out loads of stuff 
Designed new ticketing system 
Fixed [[FOH Sound|FoH Sound System]] 

==Fringe 2007==

*Fringe Venue Manager: Matt Wieteska
*Theatre Manager: Colleen Patterson
*Technical Manager: Neale Dutton
*Press and Publicity Manager: Lucy Jackson
*Graphics Designer: Nick Kay
*Sponsorship Manager: Becs Kamp
*Box Office Managers: Alex Hall and Mike Smith
*Cafe Managers: James "Bruce" Sinclair and Holly Mclay
*Box Office Staff: Lauren McLeod, Kate Wieteska, Felix Trench, Reg Scott, Chloe Edworthy, Mairi Kellock, Cat Hoyle, Becs Kamp
*Cafe Staff: Lauren Fried, Becca Day-Preston, Chris Cotter, Craig Hamilton

'''Achievements:'''

*Built a wall in the [[auditorium]] to help with soundproofing
*Reskinned the [[stage]]
*New [[box office]] printer
*Installed [[sound]] system

==Fringe 2006==

*Fringe Venue Manager: Charlotte Jarvis
*Theatre Manager: Alex Engel
*Technical Manager: Matt Wieteska
*Press and Publicity Manager: Simon Hodges
*Graphics Designer: Chris Mounsey
*Box Office Managers: Helena Larkin and Tom Latter
*Café Managers: Clemmie Cooke and Charlotte Coles
*Box Office Staff: Cat Hoyle, James Turner Inman, Richard Shore, Katy Bartholomew, Colleen Patterson, Natalia Prochnicka and Geraldine Heaney
*Cafe Staff:

'''Achievements:'''

*Replaced blackout [[curtains]] on [[balcony]] with new black fabric
*New coffee machine with fancy coffee capabilities for [[cafe]]
*Built large schedule chalkboards for outside
*Painted [[office]] white and blue
*Reskinned the [[stage]]

==Fringe 2005==

*Fringe Venue Manager: Claire Glendenning
*Theatre Manager: James Turner-Inman
*Technical Manager: Paul Foxcroft
*Press and Publicity Manager: Andrew Nielson
*Graphics Designer: Chris Mounsey
*Box Office Managers: Heather Hanshaw + Nick Bustin
*Café Managers: Graeme Wright + Becca Davis
*Box Office Staff: Jeremy Bidgood, Rob Stott, Rosie Drew, Alex Engel, Charlotte Jarvis
*Cafe Staff: Emma Drage,

'''Achievements:'''

*Replaced carpet in [[auditorium]] with carpet tiles
*New freezer
*Improved [[box office]] system with thermal ticket printer and new software
*Re-hung rig (termtime budget?)
*Created trus-based awning for front of building (sponsored by Becks)
*Installed ADSL [[internet connection]], network cabling and wireless network
*Loads of painting
*Improved soundproofing in between [[café]] and [[auditorium]] around the door
*Pimped up the [[office]]
*New storage solutions in [[techbox]] and [[balcony]] for screws and stuff
*Various new bits and bobs for the [[café]] e.g. tea light lanterns
*Purchase of Dog (who is a rabbit) [and is very cute]
*Re-skinned [[stage]]
*Sanded down and varnished [[cafe]] floor

==Fringe 2004==

*Fringe Venue Manager: Miriam Raines
*Theatre Manager:
*Technical Manager: James Turner-Inman
*Press and Publicity Manager:
*Graphics Designer:
*Box Office Managers: Paul Foxcroft, Martin Cavanagh
*Café Managers:
*Box Office Staff:
*Cafe Staff:

==Fringe 2003==

*Fringe Venue Manager: Cat Smith
*Theatre Manager: Jono Ellis
*Technical Manager: Matt Ling
*Press and Publicity Manager: Sarah Cook
*Graphics Designer/Website: Neil E. Hobbs
*Box Office Managers: Alison Timms and Kirsten Morris
*Café Managers: Victoria Tills and Kati Hind
*Box Office Staff:
*Cafe Staff:
 
'''Achievements:''' 
*New potato oven and chiller cabinet for [[cafe]]
*New [[sound]] system - two speakers, mini disc players, new MC2 amp, graphics - paid for by profit from Fringe 2002 (!)
*New level in [[costume cupboard]] - see graffiti!
*Skinned [[stage cupboard]] for the first time and removed wall and rail allowing it to become a stage pit
*Redid [[cafe]] and [[toilets]]
*Installed fan in [[cafe]] to improve ventilation
*Obtained two microwaves
*Redid [[kitchen]] - repainted and tiled walls, obtained new oven and hobs
*Cut down number of [[EUTC]] slots to two
*Held first [[FOB]] [[A_to_Z#AGM_-_Annual_General_Meeting|AGM]]
*Held first full preview week schedule
*Held art exhibition in collabaration with ECA
*Bought picnic table to extend [[cafe]] area (buy a new one!)
*Made more money than Graeme Timms (sorry long standing debate!)

==Fringe 2002==

*Fringe Venue Manager: Graeme Timms
*Theatre Manager: Richard Hogg
*Technical Manager: Matt Gray
*Press and Publicity Manager: Neil E. Hobbs
*Graphics Designer/Website: Neil E. Hobbs
*Box Office Managers: Pete Lowden and Sarah Kerr
*Café Managers: Cat Smith and Rachel Mountfield
*Box Office Staff:
*Cafe Staff:
 
'''Achievements:''' 
*Replaced damaged floorboards on [[stage]] during re-skinning
*Dug out back passage and laid path and red chips round that side of building
*Re-built [[box office]] counter
*Installed Tramp-Cam
*Much re-wiring of light fittings and sockets
*Computerised the [[Box office]] ticketing system
*Built the Info-Cat - (He never quite became a cat)
*Replaced lighting in [[toilets]]
*Rebranded '''Bedlam Fringe''' as a separate entity from term-time operation
*First website with up-to-date reviews, show info, etc
*Much painting
*Consumption of the more Caley Golden Promise that the Cash and Carry could stock!!

XTS

2008-07-25T17:38:15Z

Xander: /* What I plan to write about */

== eXtensible Ticketing System ==

This page is a stub. I intend to document as much of the ticketing system as possible but keep forgetting things that I want to write about. Until it's completed, here's a list of sections that I intend to write under. This article is currently aimed at people who want to maintain the source code, NOT people who want to learn how to sell tickets.

== What I plan to write about ==

* History / Motivation
* Things you should know before you start
** Key Concepts and Terminology
*** "Reserved" vs. "Booked".
*** "Holding" tickets.
*** "Ticket Prototypes"
*** "Snewts"
*** How XTS handles times between 0AM and 3AM.
** Principles
*** Portability (OS Transparency)
*** Accessibility (Network Transparency)
*** Extensibility
*** Readability
*** Simplicity (Minimum Complexity in the Layers that Matter)
*** High-Level Scripting
* Technologies in use
** HTTP
** XML
** HTML
** CSS
** Python
** Java
* Parts of the system
** Database
*** Scheduled Database Backup
** DONE Ticket Server
*** DONE Web.py
*** DONE API
** Print Server
*** API
*** Making new ticket layouts
*** Changing the ticket logo
** Static Server
*** Apache 2.2
** Administration Server
** Javascript Client
*** Ami
*** Snewts
*** Prism
** Reporting
*** XSLT
** HTTPProxy
*** Protecting the ticketing server from the proxy
** Startup - Windows Services
*** JSWrapper
* Directory Structure (C:\XTS\)
* Installing XTS
* Making Improvements - A HOWTO
** Known Issues / Things you might like to work on
*** Sniffing attacks
*** No test suite, no TDD
*** Transactions (there aren't any)
*** Printing - it's pretty crap
*** Reports - XSLT, but not as it should be
** Familiarisation
*** Grokking the Source
** Tools You Must Use
*** Firebug
*** IPython
** Things You Must Do
*** Setting up your own dev version from trunk
*** Working on a test data set
*** Keeping the documentation up-to-date
** Safe and Unsafe
*** Where is the money?
** Versioning

= Documentation =

== Parts of the System ==

=== Database ===

XTS uses a MySQL database. It should be very easy to port XTS to other databases, most access is abstracted through [[#web.py]]'s db module but there may be some report-generating SQL queries that are specific to MySQL in the XTS source. See [[#data.py]] for more info.

The schema is called "xts".

==== Scheduled Database Backups ====

As of 2008-07-18, [[Maude]] is configured to take nightly backups of the XTS database to C:\XTS\Backups. These backups should be scaled back to weeklies or slower at the end of Fringe 2008 or they '''will''' eventually consume all available disk space on the machine. Furthermore the database should occasionally be backed up "off-site" in case of hard disk failure.

=== Ticket Server ===

The ticket server does the hard work of allocating, booking and selling tickets of various types for various performances of various shows. The ticket server is written in [[#Python]]. It is implemented on top of a web server ([http://www.webpy.org web.py]]), allowing clients to interact with the server via [[#HTTP]] using [[#XML]] for data exchange.

==== API ====

API stands for Application Programming Interface. It tells you how you can write programs that talk to the ticket server in order to do useful things (like get show information, or sell tickets online).

The [[#Javascript Client]] uses the XTS API to make a nice box office interface for selling tickets to customers.

If you know a little XML and HTTP you can write programs that interact with the API yourself.

See [[XTS API]] for further information and full documentation.

==== Security ====

The ticket server uses host and password authentication to decide who can do what using the API. Full details are in the [[XTS API|API documentation]].

==== Error Handling ====

When the server encounters an error (for instance, a ticket that you are selling has already been sold), internally it throws a SnewtsError exception.

SnewtsErrors are caught by the request dispatcher (snewtsUrlInvocation in server.py) and turned into an XML-formatted error that is sent back to the client.

SnewtsErrors consist of an error number (useful to computers) and an error message (useful to people). Errors are grouped into types. For instance, all errors that start with the number 404 represent a requested thing not being there ("Not Found"). However, 404.1 specifically means that it was a ticket that wasn't found. 404.2 means a performance wasn't found and so on.

This is important when writing software that talk to the ticket server via the [[#API]]. When reading responses from the server the client software can have a default way of handling 404 errors but additionally can have a specific way of handling 404.5 errors.

Where possible, error numbers correspond to the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html HTTP status code definitions]. This is mostly because I'm perverse and think it's funny that when something isn't there you get a 404 error. However, it can be useful when writing your client software in that a 4xx error indicates that the client probably did something wrong whereas 5xx errors indicate that something went wrong on the server (which is potentially much more serious).

==== Source ====

Alphabetically:

===== constants.py =====

Contains various useful constants used in the rest of the XTS source. This makes the code more readable. In the database, the number 2 represents a ticket that is booked. However, instead of using the number 2 to refer to such tickets in the source code, we use the expression <code>ticketstates['BOOKED']</code>. This makes the code (a lot) more readable.

Funnily enough, it's generally a bad idea to change the constants. However, you should add to them where appropriate, for instance, if you intend to record new kinds of events in the log.

''There is nothing technically '''constant''' about the variables in constants.py - they could easily be modified at runtime. If you know how to define constants that are actually constant, or just of a better general approach, then this might be an area of the server that you could improve.''
--[[User:Xander|Xander]] 17:21, 18 July 2008 (BST)

===== data.py =====

data.py provides an interface to the database. Wherever XTS needs to get information from the database, it does it by calling a function in data.py. data.py then takes care of turning the information request into SQL, and if necessary, post-processing the response into a useful form for the caller.

You should be able to port XTS to another datastore simply by replacing data.py.

===== exceptions.py =====

exceptions.py defines the SnewtsError exception type. For more information, see [[#Error_Handling]].

===== helpers.py =====

helpers.py contains various functions that help to solve common and recurring problems in the Snewts application (for instance, turning datetime objects into human-readable date strings). This unclutters [[#logic.py]], which should just contain the business logic of how to sell tickets properly. Functions in helpers.py should ideally be moved into [[#XWF]], but who really cares?

===== logic.py =====

logic.py sits between the client request and the database. When the client asks to sell a ticket, logic.py makes sure that the show actually exists, the ticket is valid for the performance, there are enough tickets left and anything else that needs making sure of. If any one bit of XTS is going to get something critically wrong, it's going to be in logic.py.

logic.py never talks to the database directly. To get data from the database and make changes to the database it must call functions in [[#data.py]].

===== printer.py =====

printer.py is an abstraction layer with one synchronous public function, printTicket(). It takes care of sending the ticket to the printer and making sure that the printer got the ticket. If the print can't be confirmed it throws a SnewtsError.

===== report.py =====

report.py contains all of the code that formats statistics gathered from the database into XML reports. It also does a little math. See [[#Reporting]].

===== snewts.py =====

snewts.py does the job of recognising requests from clients, checking that the clients are authorised to make the requests, and sending back responses. Simple requests (ie. getPerformances) are fulfilled by getting data from [[#data.py]] directly. More complicated requests are fulfilled by calling business logic in [[#logic.py]] or getting [[#report.py]] to generate reports.

===== status.py =====

status.py contains definitions of all of the errors that XTS may reply with when something goes wrong. If you're writing client software, you need to anticipate these coming back at you.

XTS API

2008-07-25T17:34:23Z

Xander: /* General Errors */

= XTS Application Programming Interface =

Correct (though incomplete) as of 2008-07-18 (RC1 "Fat Cat")

 
= General Errors =
These errors can occur when calling any command, or when calling a command incorrectly. Errors are returned as an [[#<error>]] document.
* '''401 notAuthorised''' You are not authorised to perform the action. You may need to supply a password, or it might simply be impossible to do what you want to do from the machine you're on.
* '''400.1 unrecognisedCommand''' The command is not recognised. Either you spelled it wrong, the API has changed since the documentation was written or you're simply doing it wrong.

 

= Commands =

== getshows ==
=== Parameters ===
* No parameters (yet)
=== Returns ===
A <shows> document containing [[#<showsummary>]]s representing all shows in the database.
=== Errors ===
* Never returns an error.

== getshow ==
=== Parameters ===
* '''showid''' The ID of the show to get.
=== Returns ===
A [[#<show>]] representing the show.
=== Errors ===
* '''404.3 showNotFound''' if the show doesn't exist in the database.

== getperformances ==
=== Parameters ===
* '''showid''' The ID of the show to get the performances of.
=== Returns ===
A <performances> document containing [[#<performance>]]s representing all performances for the specified show.
=== Errors ===
* '''404.3 showNotFound''' if the show doesn't exist in the database.

== getperformance ==
=== Parameters ===
* '''performanceid''' The ID of the performance to get.
=== Returns ===
A [[#<performance>]] representing the performance.
=== Errors ===
* '''404.2 performanceNotFound''' if the performance doesn't exist in the database.

 
= XML =

== <error> ==
Details an error that occured while processing your request.
=== Elements ===
* '''@type''' The type number of the error, consists of a major and an (optional) minor part separated by a decimal point.
* '''<message>''' A human-readable description of the error.
=== Example ===
<code xml>
<error type="400.1">
<message>Unrecognised command.</message>
</error>
</code>

== <showsummary> ==
Gives some summary details about a show in the database.
=== Elements ===
* '''<id>''' The ID of the show.
* '''<name>''' The name of the show.
* '''<tagline>''' The show's tagline / strapline / subtitle.
=== Example ===
<code xml>
<showsummary>
<id>1</id>
<name>Alice In Wonderland</name>
<tagline>Texas Woman's University</tagline>
</showsummary>
</code>

== <show> ==
A <show> tag describes a single show in the database.
=== Elements ===
* '''<id>''' The ID of the show.
* '''<name>''' The name of the show.
* '''<tagline>''' The show's tagline / strapline / subtitle.
* '''<description>''' The show's description, if supplied. The usefulness of this field is debatable. I imagined it would carry publicity information that could be insta-formatted into web pages on the Bedlam Theatre website. Perhaps we should leave this tag as "reserved for future deprecation".
=== Example ===
<code xml>
<show>
<id>15</id>
<name>Assassins</name>
<tagline>Rather Like a Shark/DULOG</tagline>
<description/>
</show>
</code>

== <performance> ==
A <performance> tag describes a single performance in the database.
=== Elements ===
* '''<id>''' The ID of the performance.
* '''<showid>''' The ID of the performance.
* '''<start>''' The start time of the performance in seconds since the UNIX epoch.
* '''<startdatetime>''' The human-readable start time of the performance.
* '''<tickets>''' Ticket details incorporating:
** '''<total>''' The total number of seats for the performance (ie the maximum number of tickets that can be sold).
** '''<sold>''' The number of tickets that have been sold (net).
** '''<booked>''' The number of tickets that are still booked (ie, awaiting collection).
** '''<heldback>''' The number of tickets that are held back, ie, reserved for later sale.
** '''<remaining>''' The number of tickets that are immediately available for sale.
=== Example ===
<code xml>
<performance>
<id>1</id>
<showid>1</showid>
<start>1217841300</start>
<startdatetime>2008-08-04 10:15</startdatetime>
<tickets>
<total>90</total>
<sold>0</sold>
<booked>1</booked>
<heldback>18</heldback>
<remaining>71</remaining>
</tickets>
</performance>
</code>

XTS API

2008-07-18T17:21:17Z

Xander: This will do for today.

= XTS Application Programming Interface =

Correct (though incomplete) as of 2008-07-18 (RC1 "Fat Cat")

 
= General Errors =
These errors can occur when calling any command, or when calling a command incorrectly. Errors are returned as an [[#<error>] document.
* '''401 notAuthorised''' You are not authorised to perform the action. You may need to supply a password, or it might simply be impossible to do what you want to do from the machine you're on.
* '''400.1 unrecognisedCommand''' The command is not recognised. Either you spelled it wrong, the API has changed since the documentation was written or you're simply doing it wrong.

 
= Commands =

== getshows ==
=== Parameters ===
* No parameters (yet)
=== Returns ===
A <shows> document containing [[#<showsummary>]]s representing all shows in the database.
=== Errors ===
* Never returns an error.

== getshow ==
=== Parameters ===
* '''showid''' The ID of the show to get.
=== Returns ===
A [[#<show>]] representing the show.
=== Errors ===
* '''404.3 showNotFound''' if the show doesn't exist in the database.

== getperformances ==
=== Parameters ===
* '''showid''' The ID of the show to get the performances of.
=== Returns ===
A <performances> document containing [[#<performance>]]s representing all performances for the specified show.
=== Errors ===
* '''404.3 showNotFound''' if the show doesn't exist in the database.

== getperformance ==
=== Parameters ===
* '''performanceid''' The ID of the performance to get.
=== Returns ===
A [[#<performance>]] representing the performance.
=== Errors ===
* '''404.2 performanceNotFound''' if the performance doesn't exist in the database.

 
= XML =

== <error> ==
Details an error that occured while processing your request.
=== Elements ===
* '''@type''' The type number of the error, consists of a major and an (optional) minor part separated by a decimal point.
* '''<message>''' A human-readable description of the error.
=== Example ===
<code xml>
<error type="400.1">
<message>Unrecognised command.</message>
</error>
</code>

== <showsummary> ==
Gives some summary details about a show in the database.
=== Elements ===
* '''<id>''' The ID of the show.
* '''<name>''' The name of the show.
* '''<tagline>''' The show's tagline / strapline / subtitle.
=== Example ===
<code xml>
<showsummary>
<id>1</id>
<name>Alice In Wonderland</name>
<tagline>Texas Woman's University</tagline>
</showsummary>
</code>

== <show> ==
A <show> tag describes a single show in the database.
=== Elements ===
* '''<id>''' The ID of the show.
* '''<name>''' The name of the show.
* '''<tagline>''' The show's tagline / strapline / subtitle.
* '''<description>''' The show's description, if supplied. The usefulness of this field is debatable. I imagined it would carry publicity information that could be insta-formatted into web pages on the Bedlam Theatre website. Perhaps we should leave this tag as "reserved for future deprecation".
=== Example ===
<code xml>
<show>
<id>15</id>
<name>Assassins</name>
<tagline>Rather Like a Shark/DULOG</tagline>
<description/>
</show>
</code>

== <performance> ==
A <performance> tag describes a single performance in the database.
=== Elements ===
* '''<id>''' The ID of the performance.
* '''<showid>''' The ID of the performance.
* '''<start>''' The start time of the performance in seconds since the UNIX epoch.
* '''<startdatetime>''' The human-readable start time of the performance.
* '''<tickets>''' Ticket details incorporating:
** '''<total>''' The total number of seats for the performance (ie the maximum number of tickets that can be sold).
** '''<sold>''' The number of tickets that have been sold (net).
** '''<booked>''' The number of tickets that are still booked (ie, awaiting collection).
** '''<heldback>''' The number of tickets that are held back, ie, reserved for later sale.
** '''<remaining>''' The number of tickets that are immediately available for sale.
=== Example ===
<code xml>
<performance>
<id>1</id>
<showid>1</showid>
<start>1217841300</start>
<startdatetime>2008-08-04 10:15</startdatetime>
<tickets>
<total>90</total>
<sold>0</sold>
<booked>1</booked>
<heldback>18</heldback>
<remaining>71</remaining>
</tickets>
</performance>
</code>

XTS API

2008-07-18T17:03:17Z

Xander:

XTS API

2008-07-18T17:02:27Z

Xander:

== XTS Application Programming Interface ==

Correct (though incomplete) as of 2008-07-18 (RC1 "Fat Cat")

 
= General Errors =
These errors can occur when calling any command, or when calling a command incorrectly. Errors are returned as an [[#<error>] document.
* '''401 notAuthorised''' You are not authorised to perform the action. You may need to supply a password, or it might simply be impossible to do what you want to do from the machine you're on.
* '''400.1 unrecognisedCommand''' The command is not recognised. Either you spelled it wrong, the API has changed since the documentation was written or you're simply doing it wrong.

 
= Commands =

== getshows ==
=== Parameters ===
* No parameters (yet)
=== Returns ===
A <shows> tag containing [[#<showsummary>]]s representing all shows in the database.
=== Errors ===
* Never returns an error.

== getshow ==
=== Parameters ===
* '''showid''' The ID of the show to get.
=== Returns ===
A [[#<show>]] representing the show.
=== Errors ===
* '''404.3 showNotFound''' if the show doesn't exist in the database.

 
= XML =

== <error> ==
Details an error that occured while processing your request.
=== Elements ===
* '''@type''' The type number of the error, consists of a major and an (optional) minor part separated by a decimal point.
* '''<message>''' A human-readable description of the error.
=== Example ===
<code xml>
<error type="400.1">
<message>Unrecognised command.</message>
</error>
</code>

== <showsummary> ==
Gives some summary details about a show in the database.
=== Elements ===
* '''<id>''' The ID of the show.
* '''<name>''' The name of the show.
* '''<tagline>''' The show's tagline / strapline / subtitle.
=== Example ===
<code xml>
<showsummary>
<id>1</id>
<name>Alice In Wonderland</name>
<tagline>Texas Woman's University</tagline>
</showsummary>
</code>

== <show> ==
A <show> tag describes a single show in the database.
=== Elements ===
* '''<id>''' The ID of the show.
* '''<name>''' The name of the show.
* '''<tagline>''' The show's tagline / strapline / subtitle.
* '''<description>''' The show's description, if supplied. The usefulness of this field is debatable. I imagined it would carry publicity information that could be insta-formatted into web pages on the Bedlam Theatre website. Perhaps we should leave this tag as "reserved for future deprecation".
=== Example ===
<code xml>
<show>
<id>15</id>
<name>Assassins</name>
<tagline>Rather Like a Shark/DULOG</tagline>
<description/>
</show>
</code>

XTS API

2008-07-18T16:44:57Z

Xander:

== XTS Application Programming Interface ==

Correct (though incomplete) as of 2008-07-18 (RC1 "Fat Cat")

== getshows ==
=== Parameters ===
* No parameters (yet)
=== Returns ===
<shows> containing [[#<show>]]s representing all shows in the database.
=== Errors ===
* Never returns an error.

== getshow ==
=== Parameters ===
* '''showid''' The ID of the show to get.
=== Returns ===
A [[#<show>]] representing the show.
=== Errors ===
* '''404.3 showNotFound''' if the show doesn't exist in the database.

XTS API

2008-07-18T16:42:01Z

Xander:

== XTS Application Programming Interface ==

Correct (though incomplete) as of 2008-07-18 (RC1 "Fat Cat")

=== getshows ===
==== Parameters ====
* No parameters (yet)
==== Returns ====
<shows> containing [[#<show>]]s representing all shows in the database.
==== Errors ====
* Never returns an error.

=== getshow ===
==== Parameters ====
* '''showid''' The ID of the show to get.
==== Returns ====
A [[#<show>]] representing the show.
==== Errors ====
* '''404.3 showNotFound''' if the show doesn't exist in the database.

XTS API

2008-07-18T16:41:22Z

Xander: This may also take a while.

== XTS Application Programming Interface ==

Correct (though incomplete) as of 2008-07-18 (RC1 "Fat Cat")

=== getshows ===
== Parameters ==
* No parameters (yet)
== Returns ==
<shows> containing [[#<show>]]s representing all shows in the database.
== Errors ==
* Never returns an error.

=== getshow ===
== Parameters ==
* '''showid''' The ID of the show to get.
== Returns ==
A [[#<show>]] representing the show.
== Errors ==
* '''404.3 showNotFound''' if the show doesn't exist in the database.

XTS

2008-07-18T16:32:16Z

Xander:

== eXtensible Ticketing System ==

This page is a stub. I intend to document as much of the ticketing system as possible but keep forgetting things that I want to write about. Until it's completed, here's a list of sections that I intend to write under. This article is currently aimed at people who want to maintain the source code, NOT people who want to learn how to sell tickets.

== What I plan to write about ==

* History / Motivation
* Things you should know before you start
** Terminology
*** "Reserved" vs. "Booked".
*** "Holding" tickets.
*** "Ticket Prototypes"
*** "Snewts"
** Principles
*** Portability (OS Transparency)
*** Accessibility (Network Transparency)
*** Extensibility
*** Readability
*** Simplicity (Minimum Complexity in the Layers that Matter)
*** High-Level Scripting
* Technologies in use
** HTTP
** XML
** HTML
** CSS
** Python
** Java
* Parts of the system
** Database
*** Scheduled Database Backup
** DONE Ticket Server
*** DONE Web.py
*** DONE API
** Print Server
*** API
*** Making new ticket layouts
*** Changing the ticket logo
** Static Server
*** Apache 2.2
** Administration Server
** Javascript Client
*** Ami
*** Snewts
*** Prism
** Reporting
*** XSLT
** HTTPProxy
*** Protecting the ticketing server from the proxy
** Startup - Windows Services
*** JSWrapper
* Directory Structure (C:\XTS\)
* Installing XTS
* Making Improvements - A HOWTO
** Known Issues / Things you might like to work on
*** Sniffing attacks
*** No test suite, no TDD
*** Transactions (there aren't any)
*** Printing - it's pretty crap
*** Reports - XSLT, but not as it should be
** Familiarisation
*** Grokking the Source
** Tools You Must Use
*** Firebug
*** IPython
** Things You Must Do
*** Setting up your own dev version from trunk
*** Working on a test data set
*** Keeping the documentation up-to-date
** Safe and Unsafe
*** Where is the money?
** Versioning

= Documentation =

== Parts of the System ==

=== Database ===

XTS uses a MySQL database. It should be very easy to port XTS to other databases, most access is abstracted through [[#web.py]]'s db module but there may be some report-generating SQL queries that are specific to MySQL in the XTS source. See [[#data.py]] for more info.

The schema is called "xts".

==== Scheduled Database Backups ====

As of 2008-07-18, [[Maude]] is configured to take nightly backups of the XTS database to C:\XTS\Backups. These backups should be scaled back to weeklies or slower at the end of Fringe 2008 or they '''will''' eventually consume all available disk space on the machine. Furthermore the database should occasionally be backed up "off-site" in case of hard disk failure.

=== Ticket Server ===

The ticket server does the hard work of allocating, booking and selling tickets of various types for various performances of various shows. The ticket server is written in [[#Python]]. It is implemented on top of a web server ([http://www.webpy.org web.py]]), allowing clients to interact with the server via [[#HTTP]] using [[#XML]] for data exchange.

==== API ====

API stands for Application Programming Interface. It tells you how you can write programs that talk to the ticket server in order to do useful things (like get show information, or sell tickets online).

The [[#Javascript Client]] uses the XTS API to make a nice box office interface for selling tickets to customers.

If you know a little XML and HTTP you can write programs that interact with the API yourself.

See [[XTS API]] for further information and full documentation.

==== Security ====

The ticket server uses host and password authentication to decide who can do what using the API. Full details are in the [[XTS API|API documentation]].

==== Error Handling ====

When the server encounters an error (for instance, a ticket that you are selling has already been sold), internally it throws a SnewtsError exception.

SnewtsErrors are caught by the request dispatcher (snewtsUrlInvocation in server.py) and turned into an XML-formatted error that is sent back to the client.

SnewtsErrors consist of an error number (useful to computers) and an error message (useful to people). Errors are grouped into types. For instance, all errors that start with the number 404 represent a requested thing not being there ("Not Found"). However, 404.1 specifically means that it was a ticket that wasn't found. 404.2 means a performance wasn't found and so on.

This is important when writing software that talk to the ticket server via the [[#API]]. When reading responses from the server the client software can have a default way of handling 404 errors but additionally can have a specific way of handling 404.5 errors.

Where possible, error numbers correspond to the [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html HTTP status code definitions]. This is mostly because I'm perverse and think it's funny that when something isn't there you get a 404 error. However, it can be useful when writing your client software in that a 4xx error indicates that the client probably did something wrong whereas 5xx errors indicate that something went wrong on the server (which is potentially much more serious).

==== Source ====

Alphabetically:

===== constants.py =====

Contains various useful constants used in the rest of the XTS source. This makes the code more readable. In the database, the number 2 represents a ticket that is booked. However, instead of using the number 2 to refer to such tickets in the source code, we use the expression <code>ticketstates['BOOKED']</code>. This makes the code (a lot) more readable.

Funnily enough, it's generally a bad idea to change the constants. However, you should add to them where appropriate, for instance, if you intend to record new kinds of events in the log.

''There is nothing technically '''constant''' about the variables in constants.py - they could easily be modified at runtime. If you know how to define constants that are actually constant, or just of a better general approach, then this might be an area of the server that you could improve.''
--[[User:Xander|Xander]] 17:21, 18 July 2008 (BST)

===== data.py =====

data.py provides an interface to the database. Wherever XTS needs to get information from the database, it does it by calling a function in data.py. data.py then takes care of turning the information request into SQL, and if necessary, post-processing the response into a useful form for the caller.

You should be able to port XTS to another datastore simply by replacing data.py.

===== exceptions.py =====

exceptions.py defines the SnewtsError exception type. For more information, see [[#Error_Handling]].

===== helpers.py =====

helpers.py contains various functions that help to solve common and recurring problems in the Snewts application (for instance, turning datetime objects into human-readable date strings). This unclutters [[#logic.py]], which should just contain the business logic of how to sell tickets properly. Functions in helpers.py should ideally be moved into [[#XWF]], but who really cares?

===== logic.py =====

logic.py sits between the client request and the database. When the client asks to sell a ticket, logic.py makes sure that the show actually exists, the ticket is valid for the performance, there are enough tickets left and anything else that needs making sure of. If any one bit of XTS is going to get something critically wrong, it's going to be in logic.py.

logic.py never talks to the database directly. To get data from the database and make changes to the database it must call functions in [[#data.py]].

===== printer.py =====

printer.py is an abstraction layer with one synchronous public function, printTicket(). It takes care of sending the ticket to the printer and making sure that the printer got the ticket. If the print can't be confirmed it throws a SnewtsError.

===== report.py =====

report.py contains all of the code that formats statistics gathered from the database into XML reports. It also does a little math. See [[#Reporting]].

===== snewts.py =====

snewts.py does the job of recognising requests from clients, checking that the clients are authorised to make the requests, and sending back responses. Simple requests (ie. getPerformances) are fulfilled by getting data from [[#data.py]] directly. More complicated requests are fulfilled by calling business logic in [[#logic.py]] or getting [[#report.py]] to generate reports.

===== status.py =====

status.py contains definitions of all of the errors that XTS may reply with when something goes wrong. If you're writing client software, you need to anticipate these coming back at you.