--- loncom/enrollment/localenroll.pm 2009/09/13 03:14:12 1.39 +++ 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.39 2009/09/13 03:14:12 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; } @@ -297,8 +317,14 @@ validate_instcode takes three arguments (c) an optional institutional username for the course owner. An array is returned containing (a) the result of the check for a valid -instcode, and (b) an (optional) course description. +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. @@ -308,7 +334,8 @@ sub validate_instcode { my ($dom,$instcode,$owner) = @_; my $outcome = ''; my $description = ''; - return ($outcome,$description); + my $credits = ''; + return ($outcome,$description,$credits); } =pod @@ -331,34 +358,44 @@ Other scenarios are possible, and the ro 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 - +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. + 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. +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) reject - the requestor should never be requesting this course, reject the + +(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 check localenroll:validate_instcode() - periodically until the status changes to "valid". + 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) = @_; + my ($dom,$owner,$crstype,$inststatuslist,$instcode,$instseclist,$custominfo) = @_; my $outcome = 'approval'; return $outcome; } @@ -374,7 +411,7 @@ lonnet -> lond -> localenroll.pm) The do 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, $reqtyes, $validations. +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" @@ -415,6 +452,94 @@ sub crsreq_checks { =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() This is called when the authentication method set for the automated @@ -521,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', @@ -536,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() @@ -728,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. @@ -738,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; } @@ -806,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