ABSTRACT

CourseSubscriptios are subcriptions of students (shibboleth data) to a CourseEvents object:

Id
Is the Identification of a CourseEvents object.

Course Event ID
Is a Reference to the CourseEvents object, to which the student subscribed.

Validation Data
The shibboleth attributes are stored in this object (not as reference to an other object). There are accessor methods for each shibboleth validation attribute.

Reminder Time
A student may get a reminder mail or SMS shortly before the course begins. reminder_by may be 'sms' or 'mail'. The email address is in reminder_to and should be 0791234567@sms.ethz.ch for reminder_by => 'sms'. reminder_time is a UNIX time which specifies when the mail should be send by a daily cronjob. reminder_time => 0 should be interpreted as send no reminder.

Participated
A flag which says, if the student participated at the course event. yes or no or a false value, which says not known.

Creation and Cancel Times
The creation time is set when the object is created on the database. The cancel time should be set when a student cancels his subscription.


METHODS

Object Constructor

$subscr = CourseSubscriptions->find( -id=>Ident )
$subscr = CourseSubscriptions->find( -course_event_id=>Ident, -UniqueID=>swissEduPersonUniqueID)
Object constructor. Subscriptions are identified by an Ident, which is unique and will never change. They could also be identified by a course_event_id and UniqueID. If the desired subscription is not found, an empty object is returned.

$subscr = CourseSubscriptions->create( );
Creates an object in memory but not on the VIP database. Its content should be set with the $subscr->update()-method, which will update the VIP database as well if the input checks pass. The first update should set at least the following attributes: course_event_id, givenName, sn, UniqueID, mail and HomeOrganization.

$aref = CourseSubscriptions->get_object_list( );
Returns a reference to a list of course subscription objects. All subscriptions are returned, they are orderd by id. There is an argument -order_by => 'sn' which will order the objects on the sn (surname) attribute, -order_by => 'HomeOrganization' sorts by HomeOrganization, -order_by => 'participated' by participated (and sn givenName).

The following arguments can be used to reduce the number of returned objects. If several arguments are specified, a subscription must match all of them.

-course_event_id => $id
ID of a CourseEvents object.

-HomeOrganization => $homeorg
A Shibboleth home organization.

-mail => $email_address
An exact email address (RFC-822).

-mail_like => $mail_domain
A string that should match the end of email addresses.

-UniqueID => $swiss_edu_person_unique_id
A shibboleth identification of a person.

-reminder_time_after => $time
-reminder_time_before => $time
A UNIX time: when should a cronjob send a reminder mail. NULL or zero should be interpreted as 'no need to send a mail'.

-canceled => 'include'
Includes canceled subscriptions in the list (default: canceled subscriptions are not included).

-canceled => 'only'
Only canceled subscriptions (default: only uncanceled subscriptions are included).

$aref = CourseSubscriptions->get_id_list( ... );
Returns a reference to a list of course idents, not blessed objects. Unsorted. Same arguments as get_object_list, but the -order_by=>'sn' argument is ignored.

Object Accessor Methods

The following methods return the current state of an object:

$string = $subscr->course_event_id;
Always defined: reference to a CourseEvents object.

$unix_time = $subscr->cancel_time;
Always defined: 0 should be interpreted as not canceled; otherwise it is a UNIX time of the cancel.

$unix_time = $subscr->creation_time;
Always defined: UNIX time value of object creation on the DB.

$string = $subscr->gender;
Always defined: 0 for persons with unknown sex, 1 for male or 2 for female persons.

$string = $subscr->givenName;
Always defined: firstname from shibboleth, iso-8859-1.

$string = $subscr->HomeOrganization;
Always defined: home org from shibboleth, iso-8859-1.

$id = $subscr->id;
Always defined: the ID of the CourseSubscriptions object.

$string = $subscr->mail;
Always defined: RFC-822 email address from shibboleth, iso-8859-1.

$string = $subscr->participated;
'yes' or 'no' or an empty string. An empty string should be interpreted as dont know if the student participated or not.

$reminder_format = $subscr->reminder_by;
Should be used to format the reminder message for 'sms' or 'mail'.

$time = $subscr->reminder_time;
Optional: UNIX time; the cronjob which sends reminder mails should interpret NULL or 0 as 'send no more roses'.

$email_addr = $subscr->reminder_to;
$string = $subscr->sn;
Always defined: surname from shibboleth, iso-8859-1.

$string = $subscr->StudyBranch1;
Optional: from shibboleth, iso-8859-1.

$string = $subscr->StudyBranch2;
Optional: from shibboleth, iso-8859-1.

$string = $subscr->StudyBranch3;
Optional: from shibboleth, iso-8859-1.

$string = $subscr->StudyLevel;
Optional: from shibboleth, iso-8859-1.

$string = $subscr->UniqueID;
Always defined: swissEduPersonUniqueID from shibboleth, iso-8859-1.

Object Modifier Method

($field, $errmsg) = $subscr->update( ... )
Updates the subscription (object state and data base permanent storage). Before any data is changed, all values are checked. If a check fails, the update will not change any data but return a list of two values: the name of the field and an error message. If all checks are ok, the update method will change the objects state in memory and on the VIP database and return undef. What will be updated is determinated by arguments as follows:
-course_event_id=>$id
Must be defined. An ID of a CourseEvents object.

-givenName=>$iso_8859_1_string
Must be defined. ISO-8859-1 string. 1 to 255 characters long.

-sn=>$iso_8859_1_string
Must be defined. ISO-8859-1 string. 1 to 255 characters long.

-gender=>number
1 for male students, 2 for female students or 0 for students without konwn sex (0 is the default).

-UniqueID=>$iso_8859_1_string
Must be defined. ISO-8859-1 string. 1 to 255 characters long.

-mail=>$iso_8859_1_string
Must be defined. ISO-8859-1 string. 1 to 255 characters long.

-HomeOrganization=>$iso_8859_1_string
Must be defined. ISO-8859-1 string. 1 to 255 characters long.

-StudyBranch1=>$iso_8859_1_string
ISO-8859-1 string. 0 to 255 characters long.

-StudyBranch2=>$iso_8859_1_string
ISO-8859-1 string. 0 to 255 characters long.

-StudyBranch3=>$iso_8859_1_string
ISO-8859-1 string. 0 to 255 characters long.

-StudyLevel=>$iso_8859_1_string
ISO-8859-1 string. 0 to 255 characters long.

-reminder_time=>$unix_time
Any false value will be translated to 0 (send no mail).

-reminder_by=>$string
'mail' or 'sms' (for -reminder_time=>$time_value) or an empty string (for -reminder_time=>0).

-reminder_to=>$string
Must be an empty string (for -reminder_time=>0) or an email address (for -reminder_by=>'mail') or an email address to the ethz SMS gateway (for -reminder_by=>'sms').

-participated=>$string
'yes' or 'no' or an empty string.

$subscr->cancel;
Cancels the subscription.

$subscr->delete;
Deletes the object, both in memory and on the VIP database.


SEE ALSO

CourseSubscriptions have a reference a CourseEvents.pm object; a CourseEvent combines a Course with a date, a Location and a TeacherGroup and adds informations like max_participants, closed and visible flag.

http://www.switch.ch/aai/ describes shibboleth.


COPYRIGHT

Copyright 2005-2014 Thedi gerber@id.ethz.ch