--- loncom/enrollment/localenroll.pm 2009/03/09 01:58:52 1.34
+++ loncom/enrollment/localenroll.pm 2014/04/30 17:17:25 1.47
@@ -1,6 +1,6 @@
# functions to glue school database system into Lon-CAPA for
# automated enrollment
-# $Id: localenroll.pm,v 1.34 2009/03/09 01:58:52 weissno Exp $
+# $Id: localenroll.pm,v 1.47 2014/04/30 17:17:25 raeburn Exp $
#
# Copyright Michigan State University Board of Trustees
#
@@ -41,8 +41,6 @@ described at http://www.lon-capa.org.
=over
-=back
-
=cut
package localenroll;
@@ -125,6 +123,8 @@ sub run() {
D
A12345678
+
+
with the following at the top of the file
@@ -149,6 +149,17 @@ sub run() {
If dates are to included in the XML file, they should be in the format
YYYY:MM:DD:HH:MM:SS (: separators required).
+ The tag need only be used if the credits earned by the students will
+ be different from the default for the course. The course default is set when the
+ course is created and can be modifed by a Domain Coordinator via "View or
+ modify a course or community" on the DC's Main Menu screen.
+
+ A value for should be the institutional status used for students,
+ and should be one of the types defined in inst_usertypes(). If no status
+ types are defined for the domain this tag can be omitted. If Autoupdate.pl
+ is enabled in your domain, updates to the institutional status set here
+ will be updated by Autoupdate.pl, should changes occur.
+
If there were 10 students in fs03nop590001, 5 students in fs03nop59o601,
8 students in fs03nop590602, and 2 students in fs03ost580002,
then $$reply{'43551dedcd43febmsul1'} = 25
@@ -235,7 +246,7 @@ sub get_sections {
The course section or crosslisted course will only be added to the list of
affiliates if 'ok' is returned.
- new_course takes three arguments -
+ new_course takes three required arguments -
(a) the institutional courseID (in the MSU case this is a concatenation of
semester code, department code, course number, and section number
e.g., fs03nop590001).
@@ -244,10 +255,14 @@ sub get_sections {
username:domain
(c) the LON-CAPA domain that contains the course
+ new_course also takes a fourth (optional) argument -
+ (d) the course co-owners, as a comma-separated list of username:domain for
+ any co-owners.
+
=cut
sub new_course {
- my ($course_id,$owner,$dom) = @_;
+ my ($course_id,$owner,$dom,$coowners) = @_;
my $outcome = 'ok';
return $outcome;
}
@@ -281,6 +296,191 @@ sub validate_courseID {
=pod
+=item validate_instcode()
+
+This is called when a request is being made for an official course.
+A check is made that the institutional code for which a course is
+is being requested is valid according to the institutional
+schedule of official classes.
+
+If the username of the course owner is provided, a more restrictive
+test is used, namely that the requestor is listed as instructor of
+record for the course in the institution's course schedule/database.
+
+validate_instcode takes three arguments -
+ (a) the LON-CAPA domain that will contain the course
+ (b) the institutional code (in the MSU case this is a concatenation of
+ semester code, department code, and course number, e.g., fs03nop590.
+ (c) an optional institutional username for the course owner.
+
+An array is returned containing (a) the result of the check for a valid
+instcode, (b) an (optional) course description, and (c) the default credits
+earned by students when completing this course. If no institutional credits
+value is available, the default credits for the course can be set via the
+course request form, or via XML in a batch file, of via the web form used
+by the Domain Coordinator to create new courses one at a time.
+
+A valid instcode is confirmed by returning 'valid'.
+
+If no course description is available, '' should be set as
+the value of the second item in the returned array.
+
+=cut
+
+sub validate_instcode {
+ my ($dom,$instcode,$owner) = @_;
+ my $outcome = '';
+ my $description = '';
+ my $credits = '';
+ return ($outcome,$description,$credits);
+}
+
+=pod
+
+=item validate_crsreq()
+
+This is used to check whether a course request should be processed
+automatically, or held in a queue pending administrative action at
+the institution.
+
+Course requests will trigger this check if the process type has been set
+to 'validate' for the course type (official, unofficial or community) and
+the requestor's affiliation. Whether "validate" is an available option
+in the Domain Configuration menu is controlled by auto_courserequest_checks().
+One scenario is where the request is for an official course, in which case
+a check could be made that the requestor is listed as instructor of
+record for the course in the institution's course schedule/database.
+
+Other scenarios are possible, and the routine can be customized according
+to whatever rules a domain wishes to implement to run validations against
+given the data passed in to the routine.
+
+validate_crsreq takes six arguments -
+ (a) the LON-CAPA domain that will contain the course.
+ (b) the username:domain for the course owner.
+ (c) the course type (official, unofficial or community)
+ (d) a comma-separated list of institutional affiliations of
+ the course owner.
+ (e) the institutional code (in the MSU case this is a concatenation of
+ semester code, department code, and course number, e.g., fs03nop590).
+ (f) a comma-separated list of institutional sections included in
+ the course request (only applicable to official courses).
+ (g) an optional reference to a hash of custom form data.
+ The custom form data will come from crsreq_updates().
+
+A valid courserequest is confirmed by returning 'process'.
+The following can be returned: process, rejected, pending, approval or
+error (with error condition - no :), followed by a : and then an optional message.
+
+(a) process - the requestor is the recorded instructor - create the course
+(b) rejected - the requestor should never be requesting this course, reject the
+ request permanently
+(c) pending - the requestor is not the recorded instructor, but could
+ become so after administrative action at the institution. Put the
+ request in a queue and, if an official course, check
+ localenroll:validate_instcode() periodically until the status changes to
+ "valid".
+(d) approval - the request will be held pending review by a Domain Coordinator.
+(e) error (followed by the error condition).
+
+=cut
+
+sub validate_crsreq {
+ my ($dom,$owner,$crstype,$inststatuslist,$instcode,$instseclist,$custominfo) = @_;
+ my $outcome = 'approval';
+ return $outcome;
+}
+
+=pod
+
+=item crsreq_checks()
+
+This is used to determine whether the "validate" option should appear in the
+possible choices for course request processing in the Domain Configuration
+menu for Course Requests. Ultimately it is called by domainprefs.pm (via:
+lonnet -> lond -> localenroll.pm) The domain configuration menu includes
+a table where columns are course type (official, unofficial or community)
+and rows are institutional affiliations (e.g., Faculty, Staff, Student etc.).
+
+crsreq_checks() takes three arguments: $dom, $reqtypes, $validations.
+$dom - the domain for which validation options are needed.
+$reqtypes - ref to an ARRAY of course types (i.e., official, unofficial and community.
+$validations - ref to a hash of a hash which will determine whether "validate"
+will be one of the possible choices for each course type (outer hash key),
+and institutional type (inner hash key).
+
+For example to allow validate to be a choice for official classes for Faculty,
+req_checks would include:
+
+$validations{'official'}{'Faculty'} = 1;
+
+This routine is closely tied to validate_crsreq(). "Validate" should not be
+a possible choice in the domain configuration menu for a particular course
+type/institutional affiliation, unless a corresponding validation code has
+been implemented in validate_crsreq().
+
+For example at MSU, official courses requested by Faculty will be validated
+against the official schedule of classes to check that the requestor is one
+of the instructors of record for the course. In this case validate_crsreq()
+includes a call to validate_instcode().
+
+=cut
+
+sub crsreq_checks {
+ my ($dom,$reqtypes,$validations) = @_;
+ if ((ref($reqtypes) eq 'ARRAY') && (ref($validations) eq 'HASH')) {
+ my (%usertypes,@order);
+ if (&inst_usertypes($dom,\%usertypes,\@order) eq 'ok') {
+ foreach my $type (@{$reqtypes}) {
+ foreach my $inst_type (@order) {
+ $validations->{$type}{$inst_type} = 0;
+ }
+ }
+ }
+ }
+ return 'ok';
+}
+
+sub crsreq_updates {
+ my ($cdom,$cnum,$crstype,$action,$ownername,$ownerdomain,$fullname,$title,
+ $code,$accessstart,$accessend,$incoming,$outgoing) = @_;
+ unless (ref($outgoing) eq 'HASH') {
+ return 'fail';
+ }
+ my %extrainfo;
+ if (ref($incoming) eq 'HASH') {
+ %extrainfo = %{$incoming};
+ }
+ if ($action eq 'review') {
+ $outgoing->{'reviewweb'} = '';
+ } elsif ($action eq 'prevalidate') {
+ $outgoing->{'formitems'} = {}; # key=>value, where key is form element name
+ # and value is multiple, if there
+ # are multiple form elements with
+ # the same name.
+ } elsif ($action eq 'process') {
+ $outgoing->{'formitems'} = {}; # key=>value, where key is form element name
+ # and value is multiple, if there
+ # are multiple form elements with
+ # the same name.
+ } elsif ($action eq 'created') {
+ $outgoing->{'createdweb'} = '';
+ $outgoing->{'createdmsg'} = [{
+ mt => '',
+ args => [],
+ }];
+ } elsif ($action eq 'queued') {
+ $outgoing->{'queuedmsg'} = [{
+ mt => '',
+ args => [],
+ }];
+ $outgoing->{'queuedweb'} = '';
+ }
+ return 'ok'
+}
+
+=pod
+
=item create_password()
This is called when the authentication method set for the automated
@@ -381,6 +581,46 @@ sub instcode_format () {
return $outcome;
}
+=pod
+
+=item possible_instcodes()
+
+Gather acceptable values for institutional categories to use in course creation request form for official courses.
+
+ requires five arguments:
+
+ domain ($dom)
+ reference to array of titles ($codetitles)
+ reference to hash of abbreviations used in categories ($cat_titles).
+ reference to hash of arrays specifying sort order used in
+ category titles ($cat_order).
+ reference to array which will contain order of component parts used
+ in institutional code ($code_order).
+
+ e.g.,
+ @{$codetitles} = ('Year','Semester',"Department','Number');
+
+ %{$$cat_titles{'Semester'}} = (
+ fs => 'Fall',
+ ss => 'Spring',
+ us => 'Summer');
+
+ @{$$cat_order{'Semester'}} = ('ss','us','fs');
+ @{$code_order} = ('Semester','Year','Department','Number');
+
+ returns 1 parameter: 'ok' if no processing errors.
+
+=cut
+
+sub possible_instcodes {
+ my ($dom,$codetitles,$cat_titles,$cat_order,$code_order) = @_;
+ @{$codetitles} = ();
+ %{$$cat_titles{'Semester'}} = ();
+ @{$$cat_order{'Semester'}} = ('ss','us','fs');
+ @{$code_order} = ();
+ return 'ok';
+}
+
=pod
@@ -557,6 +797,9 @@ sub instcode_defaults {
keys will be unique IDs (student or faculty/staff ID)
values will be either: scalar (username) or an array
if a single ID matches multiple usernames.
+ (d) $lc_users - reference to hash containing LON-CAPA usernames in
+ in domain $dom, as keys. Needed if institutional
+ data source only allows query by username.
returns 1 parameter - 'ok' if no processing error, or other value
if an error occurred.
side effects - populates the $instusers and $instids refs to hashes.
@@ -567,7 +810,7 @@ sub instcode_defaults {
=cut
sub allusers_info {
- my ($dom,$instusers,$instids) = @_;
+ my ($dom,$instusers,$instids,$lc_users) = @_;
my $outcome = 'ok';
return $outcome;
}