--- loncom/enrollment/localenroll.pm 2016/04/02 04:31:26 1.54 +++ loncom/enrollment/localenroll.pm 2021/03/31 02:19:58 1.60 @@ -1,6 +1,6 @@ # functions to glue school database system into Lon-CAPA for # automated enrollment -# $Id: localenroll.pm,v 1.54 2016/04/02 04:31:26 raeburn Exp $ +# $Id: localenroll.pm,v 1.60 2021/03/31 02:19:58 raeburn Exp $ # # Copyright Michigan State University Board of Trustees # @@ -39,8 +39,6 @@ described at http://www.lon-capa.org. =head1 NOTABLE SUBROUTINES -=over - =cut package localenroll; @@ -48,6 +46,8 @@ package localenroll; use strict; =pod + +=over =item run() set this to return 1 if you want the auto enrollment to run @@ -144,7 +144,7 @@ sub run() { Manager, or via the 'Upload a class list','Enroll a single student' or 'Modify student data' utilities in the Enrollment Manager, by checking the 'make these dates the default for future enrollment' checkbox. If no default - dates have been set, then the tudent role will be active immediately, and will + dates have been set, then the student role will be active immediately, and will remain active until the role is explicitly expired using ENRL -> Drop students. If dates are to included in the XML file, they should be in the format YYYY:MM:DD:HH:MM:SS (: separators required). @@ -207,7 +207,7 @@ sub fetch_enrollment { ("001","601","602") would be returned If the array returned contains at least one element, then - the interface offerred to the course coordinator, lists + the interface offered to the course coordinator, lists official sections and provides a checkbox to use to select enrollment in the LON-CAPA course from each official section. @@ -258,9 +258,11 @@ sub get_sections { username:domain (c) the LON-CAPA domain that contains the course - new_course also takes a fourth (optional) argument - + new_course also takes optional fourth and fifth arguments - (d) the course co-owners, as a comma-separated list of username:domain for - any co-owners. + any co-owners. + (e) database handle (might be set when new_course() is called by check_section + routine within localenroll.pm). =cut @@ -340,6 +342,32 @@ sub validate_instcode { =pod +=item validate_crosslist_access() + +This is called for an official course to check whether a course +with the institutional code can have access to enrollment data +from a cross-listed institutional section code, given a co-owner. + +validate_crosslist_access() takes four arguments - +(a) the course's LON-CAPA domain +(b) the institional course code assigned to the course +(c) the institutional course section code for the crosslisting +(d) the co-owner to check for affiliation with the crosslisting + (username:domain). + +A combination of (a), (b), (c) and (d) with access to enrollment +data, as per institutional policies, is confirmed by returning 'valid'. + +=cut + +sub validate_crosslist_access { + my ($dom,$instcode,$inst_xlist,$coowner) = @_; + my $outcome = ''; + return $outcome; +} + +=pod + =item validate_crsreq() This is used to check whether a course request should be processed @@ -542,6 +570,94 @@ sub crsreq_updates { =pod +=item export_grades() + +This routine can be customized to push grade information to some other gradebook, +LCMS, or administrative system external to LON-CAPA. + +export_grades() takes five arguments - +(a) the LON-CAPA course ID +(b) the LON-CAPA course domain +(c) a hash reference containing the following: + scope => scope of the grades (e.g., course, map or resource). + instcode => institutional course code (if an official course) + crstype => course type -- Course, Community or Placement + context => calling context, e.g., "completion" when a student completes a placement test. +(d) a perl data structure (hash of a hash) containing the grade data. + in the outer hash, the keys are student's username:domain + in the inner hash, keys are: + id => student/employee ID + lastname => student's last name + firstname => student's first name + email => student's "permannent" e-mail address + section => student's LON-CAPA course section + total => total points earned + bytitle => reference to a hash (keys are question titles, values are points + bysymb => reference to a hash (keys are symbs, i.e., unique resource identifiers). +(e) reference to a hash which will contain information to return. + keys will be the student's username:domain. Value of 1 to show grades pushed + successfully. + +=cut + +sub export_grades { + my ($cnum,$cdom,$hashref,$dataref,$outgoing) = @_; + my %info; + if (ref($hashref) eq 'HASH') { + %info = %{$hashref}; + } + if ((ref($dataref) eq 'HASH') && (ref($outgoing) eq 'HASH')) { + foreach my $key (keys(%{$dataref})) { + $outgoing->{$key} = 1; + } + return 'ok'; + } else { + return 'error'; + } +} + +=pod + +=item check_instclasses() + + This is used to supply information about which instituional course sections + and cross-listings are available to supply enrollment data, given the current + list of owner and co-owners. The data are used to populate the column titled: + "Auto-enrollment of registered students" when showing full detailed for a course + in the course catalog. + + This subroutine takes four arguments - + + (a) $owners - comma-separated list of username:domain for course owner + and co-owners. + (b) $dom - domain of course. + (c) $classes - reference to hash of institutional course sections and + crosslistings for which access to enrollment data is being checked. + (d) $validated - reference to hash which will be populated with all + keys from incoming $classes hashref, for which one or more of the + owner/co-owners has rights to access enrollment data. For each + key included in $validated hashref, corresponding value will be set to 1. + + The subroutine returns 'ok' if there is no processing error. + +=cut + + +sub check_instclasses { + my ($owners,$dom,$classes,$validated) = @_; + if ((ref($classes) eq 'HASH') && (ref($validated) eq 'HASH')) { + foreach my $class (keys(%{$classes})){ + if (&check_section($class,$owners,$dom) eq 'ok') { + $validated->{$class} = 1; + } + } + } + return 'ok'; +} + + +=pod + =item create_password() This is called when the authentication method set for the automated @@ -907,8 +1023,8 @@ sub allusers_info { institutional types to check. (g) $srchby - optional if $uname or $id defined, otherwise required. Allowed values include: 1. lastfirst, 2. last, 3. uname - corresponding to searches by 1. lastname,firstname; - 2. lastname; 3. username + 4. email, corresponding to searches by 1. lastname,firstname; + 2. lastname; 3. username; 4. e-mail address (h) $srchterm - optional if $uname or $id defined, otherwise required String to search for. (i) $srchtype - optional. Allowed values: contains, begins (defaults