Enrolment pageboy

A pageboy which provides a flexible method of sending email to students enrolled in any particular year and session in any combination of courses, programs, and/or plans.

Enrolment Pageboy

The enrolment pageboy is triggered when the CSE mail system receives a (virtual) email address of the form: enrol_addr@enrol.program where enrol_addr is a virtual address that selects students (and only students) enrolled in specified combinations of UNSW courses, programs, and plans for specified years and sessions. enrol_addr is parsed by the enrolment pageboy program which expands it into a list of addresses based on enrolment data files that are generated from the University's central enrolment system (see the section below on Enrolment Files ). What follows is a formal description of the syntax and semantics of the enrol_addr. You might prefer however, to go directly to the example section before you deal with these more formal descriptions.

Operation

Only users who are employees of CSE or who are members of Subject_Utility (as classified by the UDB) may send email directly to an enrolment pageboy address. Other users (including addresses from outside CSE) may be permitted to send email to enrolment pageboy addresses indirectly via CSE's mail alias system (mlalias). See the section below on Links with mlalias
An error message is sent back via email to the sender, and no email is sent to any other recipient, if:
- The user is not authorized to send to the enrolment pageboy;
- There is an error in the enrolment address specification;
- The enrolment specification expands into an empty list (ie: there are no recipients)
The enrolment pageboy virtual address remains in the To: address line in the email header of the email that is finally sent to all recipients. The final expanded list of recipient addresses matching the virtual address remains hidden from all recipients.
If the sender sends an empty email message to an enrolment pageboy address, then the list of email addresses of the students matching the enrolment specification will be sent back to the sender, and no email is sent to the recipients at all.
If the sender uses either of the listing options, then the list of addresses and/or registration numbers will be sent back to the sender.

Address Specification

Syntax


      address		= enrol_addr '@enrol.program'
      enrol_addr	= enrol_spec {options} [back_ref]
      enrol_spec	= enrol_spec '.' enrol_spec '.' binaryop
			| enrol_spec '.' unaryop
			| [ yrsess '.' ] ( course | plan | program )
      binaryop		= 'and' | 'or' | 'sub'		# requires two preceeding operands
      unaryop		= 'not'				# requires one preceeding operand
      yrsess		= year session
			| 'curr'  | 'next'  | 'prev'
      year		= num{4}			# eg: 2008
      session		= ('s'|'x') ('1'|'2')		# eg: s2
      course		= unit courseno
			| 'course=' prefix
			| coursefield '=' alphanum+
			| 'hons' | 'csecourse'		# course shortcuts
                        | 'yr1' | 'yr2' | 'yr3' | 'yr4' # course shortcuts

      courseno		= num{1..4}			# one to four course numbers
							# eg: 1091, 109, 10, 1
      coursefield	= 'type'|'id'|'school'|'lec'|'lab'|'tut'|'tlb'

      plan		= unit [plan_id]
			| 'plan=' prefix
			| 'cse' | 'pv'			# plan shortcuts

      plan_id		= alpha [ alphanum num{0..5} ]	# eg: A13645, AM3, A

      program		= prog_no
			| 'program=' prefix
			| 'ug' | 'pgc' | 'pgr' | 'phd'	# program shortcuts

      prog_no		= num{1..4}			# one to four program numbers
							# eg: 3645, 364, 36, 3
      unit		= alpha{4}			# four alphabetics
							# eg: COMP, SENG, BINF, SOLA, MATH
      options		= addr_option | list_option
      addr_option	= '-unsw' | '-cse'		# default: '-cse'
      list_option	= '-addr' | '-regno'		# default:
							none
      back_ref		= '.alias=' mlalias_name

      alpha		= 'A'..'Z'			# any alphabetic character
      num		= '0'..'9'			# any numeric character
      alphanum		= alpha | num			# any alphanumeric

Description

Parsing

The enrolment specification is read, parsed and evaluated from left to right.
Case is not significant.

Plans:

Plan enrolments are specified by:

At least the first four letters of the plan prefix on their own. eg: COMP, COMPA1, COMPA23645
plan=prefix where prefix is at least one character.
One of the plan shortcuts (described here)

Programs:

Program enrolments may be specified by:

At least the first number of the program on its own. eg: 1650, 72, 3
program=prefix where prefix is at least one character.
One of the program shortcuts (described here)

Courses:

Course enrolmets are specified by:

At least the first five letters of the course prefix on their own. eg: COMP1, COMP39, COMP4911
course=prefix where prefix is at least one character.
One of the course shortcuts: 'hons' or 'csecourse' (described here).
the values of certain associated fields in the course enrolment record. The following fields are associated with course enrolments:
- TYPE: This field defines the course enrolment type. It can have the following values: LAB (laboratory), LEC (lecture), TUT (tutorial), TLB (tutlab).
- ID: Each type of course enrolment (eg: tutorial) has an associated identifier (eg: "T13A")
- SCHOOL: This identifies the school (or "Organisational Unit") that runs the course enrolment type (ie: the tutorial, lab, or lecture).
- LEC: This is a shortform which specifies the TYPE and ID together. Thus: "LEC=value" is equivalent to "TYPE=LEC.ID=value.and."
- LAB: This is a shortform which specifies the TYPE and ID together. Thus: "LAB=value" is equivalent to "TYPE=LAB.TYPE=TLB.or.ID=value.and."
- TUT: This is a shortform which specifies the TYPE and ID together. Thus: "TUT=value" is equivalent to "TYPE=TUT.TYPE=TLB.or.ID=value.and."
- TLB: This is a shortform which specifies the TYPE and ID together. Thus: "TLB=value" is equivalent to "TYPE=LAB.TYPE=TUT.TYPE=TLB.or.or.ID=value.and."
If you want to have more than one of these course fields apply to the same record, you will need to specify them consecutively, and join them with appropriate operators (see Operators below).

Operators:

Operators may be used to combine enrolment specifications into arbitrarily complex boolean enrolment expressions. There are four operators:

The AND operator specifies that the students that match both of the two previous enrolment expressions should be selected. ie: If a student matches one enrolment expression but not the other, then the student is not selected.
The OR operator specifies that the students that match either one of the two previous enrolment expressions should be selected.
The NOT operator reverses the sense of the previous enrolment expression so that instead of selecting all students enrolled in the previously specified course, plan, or program, you select students enrolled in any course, plan, or program other than the one specified. In general, the NOT operator should immediately follow a pattern or shortcut (rather than a binary operator) as the negation of an arbitrarily complex enrolment expression is not well defined. See the note below on the combined use of NOT and SUBTRACT.
The SUB operator subtracts the last set of students from the second to last set of students. ie: if the students that match the last expression are in the set B, and the students that match the second to last expression are in the set A, then (A B SUB) is the set of students that are in A but not in B. This operator is generally used to define disjoint enrolment sets in conjunction with the NOT operator. See the note below for an example and explanation of this.

The operators and patterns are specified in POSTFIX order, which is to say that the patterns (or pattern expressions) are specified before the operators which apply to the patterns (or pattern expressions). This simplifies parsing of the expression, and effectively eliminates the need for brackets. If there are insufficient operators to combine all specified patterns or pattern expressions, then the remaining patterns (or pattern expressions) are AND'ed together. This is appropriate in many cases, and can be used to dramatically simplify the final enrolment expression (see the Examples section below).

Year and Session:

The year/session specification determines the year and session of the enrolment records to which are applied the subsequent enrolment specifiations. The enrolment year and session may be changed as many times as necessary to specify your final set of target students. If the year and session are not specified, the current year and session is assumed to apply. If the current session is undefined (ie: we are between sessions), then the previous session is used instead (which may be a summer session). Year/session may be specified in two ways:

Absolutely:

A specific a year and session may be specified by year session where year is a four digit year (starting from 1999), and session may be s1, s2 or x1.

Relatively:

All relative year/session specs refer to major sessions. Major sessions are sessions one or two, and exclude all other sessions (currently only summer session).

curr: Refers to the current year and session if we are currently in a major session, or to the previous major year and session at any other time.
prev: Refers to the previous major year and session.
next: Refers to the next major year and session.

Note:

Relative year/session specifications are typically used in automated scripts and/or aliases.
There are currently very few official non-major session enrolment records.

Back_ref

The optional backward reference allows the local mail alias database mlalias to forward email to the enrol pageboy. For more details, see this description below.

Course Shortcuts

Course shortcuts are used as an easier alternative to specifying a longer (although equivalent) series of course descriptions. These shortcuts are described in the table below which also includes their equivalent series of course descriptions.

Shortcut	Description	Equivalent
hons	Enrolled in an undergraduate honours course	COMP491.COMP493.or. SENG491.BINF491.or. BIOM592.BIOM595.BIOM596.BIOM597.or.or.or. or.or
csecourse	Enrolled in any course run by CSE. (ie: Any course controlled by the 'COMP' organisational unit)	SCHOOL=COMP
yrN	Enrolled in a year N CSE course	COMPn.SENGn.BINFn.or.or

Program Shortcuts

Program shortcuts are used as an easier alternative to specifying a longer (although equivalent) series of program descriptions. These shortcuts are described in the table below which also includes their equivalent series of program descriptions.

Shortcut	Description	Equivalent
phd	Enrolled in a PhD program	1
pgr	Enrolled in a postgraduate research program	2
pgc	Enrolled in a postgraduate coursework program	5.6.7.8.9.or.or.or.or
ug	Enrolled in an undergraduate program	3.4.or

Plan Shortcuts

Plan shortcuts are used as an easier alternative to specifying a longer (although equivalent) series of plan descriptions. These shortcuts are described in the table below which also includes their equivalent series of plan descriptions.

Shortcut	Description	Equivalent
cse	Enrolled in a CSE plan	COMP.SENG.BINF.or.or
pv	Enrolled in a PV plan	SOLA

Options

Options are used to determine the types of addresses generated and used by the pageboy, and to email back to the sender the generated lists of selected students. If no options are specified, the default option is: -cse.

Address Options

Whereas the enrolment address selects students who are, were, or will be enrolled in a course, plan, or program, many of these selected students may not have an active account at CSE either because their account may not have been created yet, or their account may have expired. Address options are used to control the types of addresses that are generated by the pageboy depending on the students' CSE account status. These addresses are then used as the recipients of the email sent to the pageboy. The effect of these options depend on whether they are specified on their own or in combination with each other:

-cse: On its own, this option generates addresses for only those students that have active CSE accounts. The addresses used are the students' CSE addresses. Students who are selected by the enrolment specification that do not have CSE accounts, have no addresses generated, and will not receive the associated email.
-unsw: On its own, this option generates UNSW addresses for all students selected by the enrolment specification regardless of whether or not they have a CSE account. UNSW addresses are of the form: z1234567@student.unsw.edu.au, which depend only on the uniwide central account and email system, and not on the CSE account and email system. Note that the generation of a UNSW address for the student does not imply that a UNSW address or account exists for the student yet (or that it might ever have existed).
-cse-unsw or -unsw-cse: When used in combination these options causes the pageboy to generate and use CSE addresses for those students with CSE accounts, and UNSW addresses for those students without CSE accounts. Note that the generation of a UNSW address for the student does not imply that a UNSW address or account exists for the student (or that it might ever have existed).

Listing Options

The following options are used to send lists back to the sender (in addition to any email that may be sent to the recipients). The lists returned depend on the addresses generated, which will depend on the address options used (described above).

-addr: Email the address list back to the sender with the subject line: "Address expansion of enrol_addr@enrol.program". The address list returned is the same as the one that is automatically sent back to the sender if an empty email message (ie: with no body) is sent to the pageboy.
-regno: Email back to the sender the list of student registration numbers corresponding to the enrolment address. The list is sent back with the subject line: "Student number expansion of enrol_addr@enrol.program". Note: the list returned corresponds to the list of addresses selected by the enrolment address, including any address options. In particular, an address specification with the address option of -cse, would send back to the sender the list of student registration numbers of only those students meeting the enrolment specification who also had an active CSE account.

The listing options are independant of each other, and may be used together (causing two separate lists to be returned to the sender).

Examples

1999s1.COMP1021

CSE addresses of all students who were enrolled in the COMP1021 course for session one of 1999. Note: The default option -cse applies here, which means that only current CSE addresses are generated, and no UNSW address are generated for any student that no longer has a CSE account.

2003s1.COMPB13645-unsw

UNSW addresses are generated and used for all students enrolled in the COMPB13645 plan for session one of 2003. UNSW addresses are generated for all students meeting this criteria, regardless of whether they still have a CSE or a UNSW account.

1650-cse-unsw

Generate addresses for all students who are currently enrolled in the 1650 program. Note:

If no year or session are specified, the current year and session are used.
CSE addresses are generated for those students with CSE accounts, while UNSW addresses are generated for those students without CSE accounts.

pgc.cse.COMP3

CSE addresses of all students currently enrolled in an postgraduate program by coursework AND in a CSE plan, AND who were also enrolled in any COMP3 course. Note that the conjunctions (the ANDs) were inserted by default.

pgc.cse.COMP3.and.and

The equivalent enrolment expression to the previous example with the ANDs explicitly specified.

2008s2.5.6.7.8.9.or.or.or.or.COMP.SENG.BINF.or.or.COMP3.and.and-cse

Fully specified equivalent to the previous example (assuming that the current year and session is 2008s2).

2008s2.COMP.SENG.or.BINF.or.COMP3.and.5.6.or.7.8.or.or.9.or.and-cse

Another equivalent, fully specified variation of the previous three examples (assuming that the current year and session is 2008s2).

2007S2.COMP.1

CSE addresses of all students enrolled in a COMP plan, in a phd program, in session 2 of 2007. Note the difference with the next example.

2007S2.COMP1

CSE addresses of all students enrolled in a COMP1 course (ie: any course starting with COMP1) in session 2 of 2007. Note the difference with the previous example.

2008s2.comp1911.cse.2008s1.comp1910.cse

All students who in session 1 of 2008, were enrolled in a CSE plan, and were enrolled in COMP1910 AND who in session 2 of 2008 were enrolled in a CSE plan and enrolled in COMP1911.

comp1911.cse.not

CSE addresses of all students currently enrolled in COMP1911 who are enrolled in any plan that is not a CSE plan.

comp1911.COMP.SENG.BINF.or.or.not.and.

Equivalent fully specified enrolment expression to the previous example. Note that in this example the NOT operator follows immediately after a binary OR operator, and not, as has been recommended elsewhere in this document, immediately after a PATTERN (like BINF). This is because the parser delays its evaluation of the enrolment specification for as long as it can, in the hope that it can join related patterns together (like COMP.SENG.BINF.or.or) and optimise the eventual evaluation. If this makes no sense to you, don't worry - just make sure that you normally use the NOT operator only after PATTERNs (or risk getting sent the cryptic error message: 'Cannot negate an evaluated expression').

comp1011.not

All students that are enrolled in any course other than COMP1011. Note that this is not the way you select those students that are not enrolled in COMP1011 because a student who is enrolled in COMP1011 and at least one other course, is obviously enrolled in a course other than COMP1011, and will therefore be selected by this enrolment specification. See the next two examples for how to select students that are not enrolled in a course (or combination of courses).

COMP1011.not.COMP1011.sub

This enrolment specification first selects the set of all students enrolled in any course other than COMP1011, and then subtracts from this the set of all students enrolled in COMP1011. This final set of students is usually what is informally meant by "all students not enrolled in COMP1011", although the size of this final set of students will depend on what other course enrolments are recorded in the enrolment files used by this pageboy. A better defined example follows.

cse.ug.and.COMP1011.COMP1021.or.sub

This first selects all students enrolled in a CSE plan who are also doing an undergraduate program, then subtracts from this the set of all students enrolled in either COMP1011 or COMP1021.

cse.ug.and.csecourse.sub

This first creates the set of all undergraduate CSE students, then subtracts from this the set of all students enrolled in any course run by CSE. This effectively selects all CSE undergraduates not enrolled in any CSE course.

COMP1911.tut=M14A

All students enrolled in the M14A tutorial in COMP1911 in the current year and session. Note: the central enrolment records relating to tutorial and lab allocations are not always kept up to date by students, and so mailing lists that rely on these sorts of course enrolment records may not always be accurate.

Enrolment files

The enrolment pageboy is entirely reliant on the accuracy and integrity of the underlying enrolment data files. As such, there are several things you might need to know about these enrolment data files that may effect the extent and accuracy of the address lists that can be produced by the enrolment pageboy.

Enrolment data files only record official student enrolments. Any student that has/had made private or unofficial arrangements with the school to enrol in any course, program, or plan will not be able to be contacted via these addresses.
Enrolment data files only extend back to session 1 of 1999.
The course enrolment data for the previous, current and next session is updated daily from the University's central enrolment system and consequently may change from day to day. The full set of program and plan enrolment data for the current session is updated weekly, although a subset of these enrolments may be obtained and updated from the daily updates. No other enrolment data files from previous years or sessions are routinely updated. These data files remain static and archival from the time that the last update was obtained for these enrolments (generally one session after the session in question has ended).
The enrolment files are also used as the basis of student UDB course/program class membership. However, you generally cannot rely on UDB membership being an accurate reflection of current enrolment. This is because the UDB enrolment based class expiry dates will usually extend beyond the end of the enrolled session and into the following session or, depending on the course or program, possibly well into the following year. For this reason, the enrolment pageboy will always provide a more accurate list of students enrolled in particular courses and/or programs in particular years and sessions than will the virtual addresses that rely directly on current UDB class membership (see virtual aliases. Although the sets of addresses produced by both methods should coincide very closely when they are produced for current enrolments anytime from the middle to end of the current session, you cannot and should not rely on this.
These enrolment files are the only local source of data refering to enrolments in CSE plans (the UDB does not store any information relating to CSE plans).

Inspecting the expanded address lists

Although the program mlalias can be used to inspect the list of addresses derived from virtual addresses based on the UDB, mlalias cannot be used to inspect the list of addresses derived from the enrolment pageboy. However, the list of addresses produced by the enrolment pageboy will be emailed back to the sender if:

The sender uses either (or both) of the Listing Options, or
The sender sends an empty email message to an enrolment pageboy address. This is equivalent to using the -addr listing option, except that no email at all is sent to the resulting recipients, and the address list is sent back with the subject line: "Empty email address expansion of enrol_addr@enrol.program".

See the section on Listing Options for more details.

Links with mlalias

The enrol pageboy system only permits users who are members of the CSE UDB classes: 'Employee' or 'Subject_Utility' to use its virtual aliases. However, other users may be allowed to use enrol pageboy aliases using CSE's mlalias system. To do this, a mlalias is created which redirects email to a specially modified enrol pageboy address as follows:

The non-standard users must either be:
- Explicitly named as one of the owners of the mlalias. Non-CSE users can be mlalias owners by adding their external (non-CSE) email address to the list of owners.
- A local user who is a member of one of the explicitly named group owners of the mlalias. Group owners start with a '@'.
The mlalias must be closed. This ensures that noone can add themselves to the mail alias that can send to the enrol pageboy alias;
The first owner of the mlalias must be a member of 'Employee'. This ensures that non-employees cannot create their own mlaliases forwarding to enrol pageboy aliases.
The enrol pageboy address to which the mlalias forwards its mail must include a special backward reference to the forwarding mlalias of the form: enrol_pageboy_spec.alias=mlalias_name@enrol.program. This is the only way that the enrol pageboy can check the sender against the mlalias owners (as described above). The enrol pageboy also confirms that it is called with the same enrol_pageboy_spec as is recorded in the mlalias system. This ensures that the enrol pageboy does not permit a non-standard user to use it with a pageboy spec that was not specified in the mlalias. The backward reference .alias=mlalias_name must occur immediately before "@enrol.program". Any address or listing options must be included at the end of the enrol_pageboy_spec, immediately before the backward reference.

Mlalias Examples

If CSE employee "sue" wanted to allow "karen@external.site.com", and CSE members of the UDB class "Random", to send email to "3927@enrol.program", then sue might create a mlalias called "XYZ" which:

Was owned by a CSE employee (typically sue herself);
Included "karen@external.site.com" as an additional owner;
Included "@random" as an additional owner;
Redirected its mail to "3927.alias=XYZ@enrol.program";

Karen could then send mail from external.site.com's mail server to current 3972 students by sending her email to "XYZ@cse.unsw.edu.au". If "XYZ" redirected its email to "3927-regno.alias=XYZ@enrol.program" instead (ie: the listing option "-regno" was included), then those users permitted to send to "XYZ" would also be sent back the expanded list of the students who were sent the email (listed as student registration numbers, not usernames). See Listing Options above.