--- loncom/enrollment/localenroll.pm 2009/08/18 20:08:38 1.37 +++ loncom/enrollment/localenroll.pm 2015/08/05 18:47:17 1.53 @@ -1,6 +1,6 @@ # functions to glue school database system into Lon-CAPA for # automated enrollment -# $Id: localenroll.pm,v 1.37 2009/08/18 20:08:38 raeburn Exp $ +# $Id: localenroll.pm,v 1.53 2015/08/05 18:47:17 raeburn Exp $ # # Copyright Michigan State University Board of Trustees # @@ -123,6 +123,8 @@ sub run() { D A12345678 + + with the following at the top of the file @@ -147,6 +149,20 @@ 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 the "Institutional user types" + section in the domain config screen for: + "Default authentication/language/timezone/portal/types" + + 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 @@ -233,7 +249,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). @@ -242,10 +258,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; } @@ -290,37 +310,234 @@ If the username of the course owner is p test is used, namely that the requestor is listed as instructor of record for the course in the institution's course schedule/database. -A valid instcode is confirmed by returning 'valid'. -In the case of a check for the instructor of record, the following can -be returned: -(a) valid - the requestor is the recorded instructor - create the course -(b) reject - 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 ina queue and 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); - -validate_instcode takes five arguments - +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. - (d) an optional comma-separated list of institutional affiliations of - the course owner. - (e) an optional comma-separated list of institutional sections included in - the course request + +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,$inststatuslist,$instseclist) = @_; + 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 seven 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(), with one + additional item: $custominfo->{'_LC_clonefrom'}, provided internally + (the courseID of the LON-CAPA course being cloned). + +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'; +} + +=pod + +=item crsreq_updates() + +This is used to customize the LON-CAPA course request process. +There are two hash references: $incoming, and $outgoing; $incoming can +contain additional information collected from the requester, whereas $outgoing +can contain custom items to send back to lonrequestcourse.pm, which creates the +HTML displayed to the user during a course request. + +Different key-value pairs may be returned to lonrequestcourse.pm in the $outgoing +hashref depending on the current action. The available actions are: +review, prevalidate, process, created and queued. + +One scenario would be to return HTML markup in: $outgoing->{'reviewweb'}, +i.e., where the action is 'review', to prompt the user to provide additional +information as part of the course request, at the request review stage, +(i.e,, the page which contains the button used to submit a completed course request). + +The HTML could contain form elements (e.g., radio buttons etc.). The value(s) +selected by the requester in those form elements will be available in the incoming +hashref, for a subsequent action, if the corresponding keys have been included +in $outgoing->{'formitems'}, i.e., $outgoing will be hash of a hash. If a +particular form item will the single valued, the value set for the key in the +inner hash in $outgoing should be 1, otherwise, if it will be multi-valued, +the value should be multiple. + +The $outgoing hashref can contain a 'formitems' key for both the prevalidate +and process actions, as calls to localenroll::crsreq_update() can originate +in lonrequestcourse::process_request() for both of those actions. + +The retrieved form values are passed to localenroll::validate_crsreq() as the +optional seventh arg (a hashref) -- $custominfo. + +=cut + +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 => [], + }]; + $outgoing->{'createdactions'} = { + environment => {}, + }; + # environment can contain key=>value for + # items to set in the course environment. + # These would be items which are NOT included + # in the items set via options in the course + # request form. Currently self-enrollment + # settings are the only ones allowed, i.e., + # internal.selfenroll_types internal.selfenroll_registered + # internal.selfenroll_section internal.selfenroll_start_access + # internal.selfenroll_end_access internal.selfenroll_limit + # internal.selfenroll_cap internal.selfenroll_approval + # internal.selfenroll_notifylist + } elsif ($action eq 'queued') { + $outgoing->{'queuedmsg'} = [{ + mt => '', + args => [], + }]; + $outgoing->{'queuedweb'} = ''; + } + return 'ok' +} + =pod =item create_password() @@ -429,14 +646,18 @@ sub instcode_format () { Gather acceptable values for institutional categories to use in course creation request form for official courses. - requires four arguments: + 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 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"); + @{$codetitles} = ('Year','Semester',"Department','Number'); %{$$cat_titles{'Semester'}} = ( fs => 'Fall', @@ -444,23 +665,22 @@ Gather acceptable values for institution 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) = @_; + my ($dom,$codetitles,$cat_titles,$cat_order,$code_order) = @_; @{$codetitles} = (); %{$$cat_titles{'Semester'}} = (); @{$$cat_order{'Semester'}} = ('ss','us','fs'); - ($$cat_titles{'Department'},$$cat_order{'Department'}) = &get_all_depts($dom); - ($$cat_titles{'Year'},$$cat_order{'Year'}) = &get_possible_years($dom); + @{$code_order} = (); return 'ok'; } - =pod =item institutional_photos() @@ -636,6 +856,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. @@ -646,7 +869,7 @@ sub instcode_defaults { =cut sub allusers_info { - my ($dom,$instusers,$instids) = @_; + my ($dom,$instusers,$instids,$lc_users) = @_; my $outcome = 'ok'; return $outcome; } @@ -714,8 +937,64 @@ sub get_userinfo { =pod +=item get_multusersinfo + + (a) $dom - domain + (b) $type - username or id + (c) $unamenames - reference to hash containing usernames of users + (d) $instusers - reference to hash which will contain info for user + as key = value; keys will be one or all of: + lastname,firstname,middlename,generation,id,inststatus - + institutional status (e.g., faculty,staff,student) + Values are all scalars except inststatus, + which is an array. + (e) $instids - reference to hash which will contain ID numbers - + 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. + + 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. + with information for specified username, or specified + id, if fifth argument provided, from all available, or + specified (e.g., faculty only) institutional datafeeds, + if sixth argument provided. + + WARNING: You need to set $outcome to 'ok' once you have customized + this routine to communicate with an instititional + directory data source, otherwise retrieval of institutional + user information will always be reported as being unavailable + in domain $dom. + +=cut + +sub get_multusersinfo { + my ($dom,$type,$usernames,$instusers,$instids) = @_; + my $outcome = 'unavailable'; + return $outcome; +} + +=pod + =item inst_usertypes() + Starting with LON-CAPA 2.11.0 use of this subroutine + is deprecated. The domain configuration web GUI + accessible to Domain Coordinators will be used to + manage institutional types. If you have previously + customized this routine, then values set there will + be used when displaying the "Institutional user types" + section in the domain config screen for: + "Default authentication/language/timezone/portal/types". + + Once you have visited that screen and saved the settings, + configuration thereafter will be via the web GUI of + values stored in the domain's configuration.db file on + the primary library server in the domain, and values in + inst_usertypes() will no longer be consulted. + Incoming data: three arguments (a) $dom - domain (b) $usertypes - reference to hash which will contain