Note that as of 30 Apr 2015 all automatic processing of the rosters as described here has been disabled, as per Council Correspondence 28 Apr 2015, item 5.5. For details of the replacement system, see here.

Technical Details of the Psalter Rostering System

Introduction

This page describes the technical details of how the GWUC wiki (ThePsalter) rosters work. It is not intended for general consumption. It is presumed that the reader has some knowledge of programmed systems, and in particular, of object-oriented programming languages.

The rostering system is written in Python (version 2.7 is used), using OO-based python modules. The automatic components are scheduled for weekly operation by a cron schedule, running on the eregnans virtual Linux server (domain name ajhurst.org).

Overview

Each roster (see ChurchRosters for a full list) is managed by a small python program, named after the roster that it manages. Thus, the roster RosterVestry is managed by a program called vestry.py, RosterWelcome by a program welcome.py, and so on. Each of these programs can take a number of parameters, the two main ones being a starting date and a date to which automatic allocations are made. A third parameter can be used to define the length of the roster, but this is seldom used, and defaults to 52 weeks beyond the starting date. Date parameters may be given in the form <Mon> <day>, where <Mon> is the first three letters of the month name (with a leading capital), and <day> is the day of the month.

To avoid giving absolute dates, each of these date parameters can be specified relative to the current date, in the form +n, where n is the number of weeks beyond the current date. n may lie in the range 0 to 52. If the allocation end date (the second parameter) is the same as the first, no automatic allocations are made. Date calculations are made to whole weeks beyond today's date, unless absolute dates are used.

A number of other parameters may be specified, controlling the volume of debugging information printed, and whether the new wiki pages are written back to ThePsalter or not. They are described in greater detail later.

Each of the managing python programs contains a class definition, an instance of which contains all the data relating to the proper operation of the allocation process. These classes all inherit from a superclass called PsalterRoster, which defines most of the functionality associated with each roster operation.

The Source Code

The source code is all managed as a literate program, and is available on-line at http://ajh.co/~ajh/parish/rosters.html. That document should contain enough documentation for the literate reader to follow the code accurately enough, but here are some brief pointers to the detailed functionality. We give a rough overview of the function of each roster sub-class method. (Note that the instance parameter is omitted for brevity.)

WhatHappens(date,times)

is a stub designed to be overridden in a sub-class, and defines the default structure of a given rostered duty for the particular roster being managed. It returns a list of roster entry tuples, one for each time or duty specified in the list times for the given day. Each tuple contains the date, time, number of people to roster, and a blank roster entry template which may be modified and inserted into the roster as required. (The template is itself structured according to other parameters specified elsewhere.)