Overview

The first address will work if the email is sent from anywhere, while the second address will only work if you have set up your mailer to send the email directly to CSE's mail server. As most people (CSE students and staff included) will either be directly using, or sending via, unsw's mail system, the preferred form of address is the first.

When the CSE email server receives an email with one of these addresses, it redirects the email to the enrol pageboy subsystem which:

• Checks that the email was from an authorised sender and/or was forwarded by a suitably constructed CSE mail alias;
• Parses the first enrol_spec after the "To:" address header, and expands it into a list of addresses based on official enrolment data coming from the University's central enrolment system (see the section below on Enrolment Files ).
• Forwards the original email (with the same headers) to each address on the expanded list.

Restrictions and Operation

• Permitted users: Only members of the following netgroups are permitted to send to an enrolment pageboy address: Employee, Subject_Utility, CSE_Utility, Subject_Lecturer, Subject_Supervisor.

  Other (non CSE) users 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

• Error messages: An error message is emailed 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 To: address list.
  • The enrolment pageboy address appearing in the To: address is retained in the email header that is finally sent to all recipients.
  • The resulting expanded address list is hidden from all recipients.
  • There can only be one enrol pageboy address in the To: address list.

    If you want to send the same email to two or more different groups of student enrolments, then you should either:

    • Send the email separately to each different enrol pageboy address; or
    • Join the different groups of student enrolments into the one enrol pageboy address using the ".or" Binary operator
• The BCC: address list.

  Email cannot be directed to the enrol pageboy via a BCC:. This is because the BCC: address is stripped out of the email header by the time the enrol pageboy receives the email, and the enrol pageboy cannot extract the pageboy address to evaluate it.

• Sending an empty email message to an enrolment pageboy address, causes:
  1. The list of email addresses of the students matching the enrolment specification to be sent back to the sender,
  2. No email to be sent to the recipients at all.
• Listing Options. If the sender uses any of the listing options, then the list of addresses and/or registration numbers will be sent back to the sender.

Examples

2020t1.COMP1021

Addresses all students who were enrolled in the COMP1021 course for term one of 2020. Note: The default option -cse-unsw applies here, which means that CSE addresses are generated for those who have CSE accounts, and UNSW address generated for students with no CSE account.

COMPB13645-unsw

A list of UNSW addresses is generated for all students enrolled in the COMPB13645 plan in the current year and term. Note:

• The current term may be the summer term (t0) which does not usually have many official enrolments.
• If the current term is undefined (ie: we are between terms) then the previous term is used instead. This might be a summer term.
• UNSW addresses are generated for all students meeting this criteria, regardless of whether they have a CSE account.

curr.1650-cse

Generate CSE addresses for all students who are enrolled in the 1650 program in the current major year and term. Note:

• The current major year and term will be either term one, two or three of the current (or previous) year. Major year/terms usually have the most numerous and complete set of official enrolments.
• If we are actually between terms, or if the current term is a summer (non-major) term, then "curr." refers to the last major year/term.
• CSE addresses are only generated for those students with CSE accounts. Those without CSE accounts do not receive the email.

pgc.yr3

CSE/UNSW addresses of all students currently enrolled in a CSE postgraduate program by coursework, AND who were also enrolled in any third year CSE course. Note that the conjunction (the AND) is implied and inserted by default.

2020t2.COMP.SENG.BINF.or.or.
5.6.7.8.9.or.or.or.or.and.
COMP3.SENG3.BINF3.or.or.and
-cse-unsw

A fully specified equivalent to the previous example (presuming the current year is 2020 and term is T2). The components: COMP.SENG.BINF.or.or selects students enrolled in a CSE plan; 5.6.7.8.9.or.or.or.or selects students doing a postgraduate by coursework program; while COMP3.SENG3.BINF3.or.or selects students enrolled in a third year CSE course.

ug.stage=2

All students enrolled in the second stage of an undergraduate CSE program

2007S2.COMP.1

CSE/UNSW addresses of all students enrolled in a COMP plan, in a phd program (a program number starting with 1), in session 2 of 2007. Note the difference with the next example.

2007S2.COMP1

CSE/UNSW 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/UNSW 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.

ug.COMP1011.COMP1021.or.sub

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

ug.csecourse.sub

Subtract from the set of all students enrolled in a CSE undergraduate program, 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.

COMP1911.tlb=?

This is an example of a field query that will email to the sender a list of all the COMP1911 tutorial or lab groups that students have enrolled in the current year and session. This inhibits the calculation of any address lists and the delivery of any accompanying non-empty email. An example of the list of values returned would be: M10A:18, H12A:19, H12B:18, F09A:15 (See the section on Field Queries)

2011s1.COMP3411.type=?

This field query emails a list of all field types that students were enrolled in session 1 of 2011 for the course COMP3411. An example of the list of values returned would be: LEC:396, TUT:395

Address Specification

Parsing

• The enrolment specification is read, parsed and evaluated from left to right.
• Case is ignored.

Syntax

Plans

• 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

• At least the first number of the program on its own. eg: 1650, 72, 3
• program=prefix where prefix is at least one character.
• The stage of the program. This may be one of:
  • stage=N for a particular stage (usually 1..6)
  • stage=f for any of the final stages: 4, 5, or 6.
  • stage=na for any program without a stage
• One of the program shortcuts (described here)

Courses

• 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', 'thesisA', 'thesisB' or 'csecourse' (described here).
• field=value where field is the name of a course enrolment field, and value is the value that this field should have in the enrolment record of the selected student. The basic fields are:
  • TYPE: This field defines the type of enrolment being recorded. It's values include: LAB (laboratory), LEC (lecture), TUT (tutorial), TLB (tutlab)
  • ID: This field defines the identifier assigned to this particular course enrolment type (eg: T13A)
  • SCHOOL: This identifies the school (or "Organisational Unit") that is responsible for running this particular course enrolment type. ie: the school responsible for running the tutorial, lab, or lecture (eg: COMPSC, ELEC)
  Thus an enrolment record for COURSE=COMP1234 with TYPE=TUT and ID=T13A, records a student's enrolment in the COMP1234 course tutorial T13A. Such enrolments might be specified by: COMP1234.TYPE=TUT.ID=T13A The next section tells you how to obtain a list of the actual valid values assigned to any particular course's fields.
• typevalue=idvalue where typevalue is the value of TYPE, and idvalue is the value of the ID. This short cut allows both TYPE and ID to be specified together, such that:

  LAB=value

  is equivalent to "TYPE=LAB.TYPE=TLB.or.ID=value.and."

  TUT=value

  is equivalent to "TYPE=TUT.TYPE=TLB.or.ID=value.and."

  TLB=value

  is equivalent to "TYPE=LAB.TYPE=TUT.TYPE=TLB.or.or.ID=value.and."

  XXX=value

  is equivalent to "TYPE=XXX.ID=value.and."

  Thus the enrolments fully specified by: COURSE=COMP1234.TYPE=TUT.ID=T13A, could also be specified by: COMP1234.TUT=T13A. The next section tells you how to obtain a list of the actual valid values assigned to any particular course's typevalue fields.

Field Queries

Field queries are probably most conveniently used when the enrol pageboy program is invoked by the priv enrol command, rather than via the email system. However, if the enrol_spec containing the field query is being expanded by the mail system (and NOT by the 'priv enrol enrol_spec' command), then:

• The list of values is emailed back to the sender with the subject line: "Value expansion of pageboy address".
• No final list of (target) addresses will be generated, which means that:
  • No email is forwarded to any address list even if non-empty email accompanies the enrol spec sent to the enrol pageboy.
  • No address list is returned to the sender even if address options or listing options are explicitly included in the enrol spec sent to the enrol pageboy

Field Query Examples

• 2011s1.COMP5678.TYPE=? would return a list of all the COMP5678 enrolment TYPEs in which there are any students enrolled in session 1 2011. eg: LEC:396, TUT:396, SEM:396
• 2011s1.COMP1234.TUT=? would return a list of all the COMP1234 tutorial IDs in which there are any students enrolled. eg: M10A:18, H12A:19, H12B:18, F09A:15

  Note that tutorials, labs, and seminars are usually given values of the form: day time id, where: M,T,W,H,F represent Monday to Friday; time is given in a 24 hour format; and id is an alphabetic character which is unique when there is more than one type assigned to the same day and time.

Operators

There are four operators:

1. The AND operator selects students that match both the previous two enrolment expressions. ie: If a student matches one enrolment expression but not the other, then the student is not selected.
2. The OR operator selects students that match either one of the two previous enrolment expressions.
3. The NOT operator reverses the sense of the previous enrolment expression. It selects students enrolled in any course, plan, or program other than the one(s) 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.
4. 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.

Year and Session

Absolutely

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

Relatively

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

curr

Refers to the current year and term if we are currently in a major term, or to the previous major year and term at any other time.

prev

Refers to the previous major year and term.

next

Refers to the next major year and term.

Note:

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

Back_ref

Shortcuts

Course Shortcuts

Plan Shortcuts

Program Shortcuts

Options

Address Options

-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@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). This is the default address option if none are explicitly given.

-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

-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 option of only -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.

-confirm

This sends confirmation email to the sender with the subject line: "Confirmation of email sent to ENROL_ADDR@enrol.program" (where ENROL_ADDR is the pageboy address used). The email includes a copy of the email sent preceded by the header line: "Email contents:", followed by a full list of the email recipients preceded by the header line: "Email recipients:". If the pageboy failed to resend, the subject line is changed to: "Failed to send email to ENROL_ADDR@enrol.program".

Inspecting the expanded address lists

1. Use: priv enrol enrol_spec This priv command is only available for use by CSE Employees on CSE machines, and invokes the enrolment pageboy program causing it to list the students matching enrol_spec on standard output. This is done sepearately from the mail system, and is particularly useful to check the list of students specified by enrol_spec before sending your email to enrol_spec@enrol.program, or to list course field values before using these values in another enrol_spec.
2. Have the enrol pageboy email the generated list back to you, the sender. This will be done if:
   1. The sender uses any of the Listing Options, which will send the generated list back to the sender while sending the email to all members of the list, or
   2. 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 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".

Links with mlalias

1. The non-standard senders must either be:
   • Explicitly named as an owner of the mlalias.
   • Explicitly named as an authorized sender to the mlalias
   • A local user who is a member of one of the explicitly named group owners of the mlalias. Group owners start with a '@'.
2. The mlalias must redirect to an enrol pageboy address of the form: 'enrol_spec@enrol.program' (and not of the form: 'enrol_spec-enrol-program@cse.unsw.edu.au')
3. The enrol pageboy address must include a backward reference to the forwarding mlalias of the form: enrol_pageboy_spec.alias=mlalias_name@enrol.program. The enrol pageboy uses this back reference to look up the mlalias in order to perform all the additional checks of the sender (as described above), and of the mlalias itself (as described below). These mlalias checks are intended to ensure that no unauthorised user can create a mlalias that redirects to any enrol pageboy address. Note: 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.
4. The mlalias must be closed. This ensures that noone can add themselves to the mail alias that can send to the enrol pageboy alias;
5. The mlalias must be public. This allows the system user that actually implements the enrol pageboy to examine the mail alias definition.
6. The first owner of the mlalias must be either a member of 'Employee' or of 'Subject_Utility'. As all users are permitted to create their own mail aliases, this restriction ensures that only trusted users can create mlaliases that are then used to forward onto enrol pageboy aliases.
7. There can be only one enrol pageboy address per mlalias. This may seem unduly restrictive, but in practice, it is a simple matter to use the .OR operator to join two separate enrol_pageboy_specs together into one

Mlalias Examples

• 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";

Overview of Plans, Programs, and Courses

The highest level of study is the PROGRAM. UNSW offers a large number of programs of study, each of which leads to a specific degree. For example, 3970 is a general science program leading to a BSc, while 3715 is program leading to a general BE/BComm double degree. Programs of study may also be classified into undergraduate programs (starting with a 3 or 4) and postgraduate programs. Postgraduate programs themselves may be further classified into postgraduate research programs (starting with a 1 or 2) or postgraduate coursework programs (starting with the remaining numbers).

Programs may have different areas of specialization, or majors, that are offered by different school within UNSW. Each of the schools participating in a program will offer a related PLAN of study in that program. Thus the School of Maths offers the MATHM13970 plan leading to a BSc majoring in Maths, while the School of Psychology offers the PSYCA13970 plan leading to a BSc majoring in Psychology. Note that the plan name includes the id of the school offering the plan, another two identifying characters, and the program number of which the plan is a part.

A COURSE on the other hand is a distinct units of study usually lasting one session, (although occasionally lasting a full year), which typically specializes in the study of one distinct or particular domain of knowledge associated with the school offering the course. Course names all start with the id of the school offering the course, followed by a unique four digit number which (depending on the school) might identify the stage, level, or domain that the course is associated with. (eg: COMP3231).

Thus a program of study may be satisfied by enrolling in, and successfully completing, one (or more) different plans of study, while plans themselves are satisfied by enrolling in, and successfully completing, a minimum number of units of study.

Many of the units of study (or courses) that comprise a plan are mandatory, and these are referred to as the core units or the core courses of the plan. However, core units will not always make up the minimum number of units of study for that plan, and students enrolled in these plans of study will often have to choose from a wide variety of optional non-core course units to make up the remaining minimum number of units. Often these units will be made up from courses that are offered by schools that are different from the school offering their plan of study.

Thus:

• Two students may be enrolled in the same program but in different plans. One of these plans may be offered by CSE, while the other may not. The student enrolled in the CSE plan is generally considered to be a CSE student administered by the CSE school office, and is (for example) entitled to a CSE account, regardless of whether or not they are currently enrolled in a CSE course. The pageboy plan specification shortcut 'cse' is specifically intended to select all such CSE students regardless of their current course enrolment.
• It is of course quite possible for students who are not enrolled in a CSE plan, to be enrolled in a CSE course. So when you are selecting subsets of students enrolled in a course or combination of courses, you need to be wary of not unintentionally restricting your selection to students enrolled in a CSE plan as well. This is particularly the case when using the pageboy program shortcuts ('ug', 'pg', 'phd', 'pgc', etc) that refer to the classification of programs into undergraduate, postgraduate, phd, postgraduate by coursework, etc. These shortcuts also implicitly select for only those students doing a CSE plan, because this was seen to be the most commonly required selection of program classifications. If however you need to select (say) ANY undergraduate (ie: not just CSE undergraduates) enrolled in course COMP1234 (in which postgraduates can presumably also enrol), then you should not use the builtin pageboy program shortcut 'ug' but instead use the underlying equivalent selection without the cse restriction (ie: use '3.4.or.COMP1234' instead of 'ug.COMP1234'

Accuracy of Generated Lists

• Official vs. Unofficial Enrolments: 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 the enrolment pageboy.
• Extent of Data: Enrolment data files only extend back to session 1 of 1999.
• Frequency of Data Updates: 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). No record is kept of the daily or weekly changes to any enrolment data, so it is not possible (for instance) to send email to only those people who were not officially enrolled (in whatever) a week ago.
• Comparison with UDB_Class-list: The enrolment files are also the basis of all student UDB course/program class membership. As UDB class membership can be used to generate the virtual mailing lists of the form UDB_Class-list, it would initially appear as if the mailing lists generated by the enrol pageboy should be identical with the virtual UDB_Class-lists. However, despite sharing the same data source, 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/or 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.
• Plan based mailing lists: The enrol pageboy is the only way of producing mailing lists based on CSE plans as the UDB does not store any information relating to CSE plans.