--- loncom/enrollment/localenroll.pm	2021/03/31 02:19:58	1.60
+++ loncom/enrollment/localenroll.pm	2022/02/27 01:43:14	1.64
@@ -1,6 +1,6 @@
 # functions to glue school database system into Lon-CAPA for 
 # automated enrollment
-# $Id: localenroll.pm,v 1.60 2021/03/31 02:19:58 raeburn Exp $
+# $Id: localenroll.pm,v 1.64 2022/02/27 01:43:14 raeburn Exp $
 #
 # Copyright Michigan State University Board of Trustees
 #
@@ -655,6 +655,101 @@ sub check_instclasses {
     return 'ok';
 }
 
+=pod
+
+=item instsec_reformat()
+
+ Inputs: $dom, $action, $instsecref
+
+ $dom is the course's domain
+ $action is either: clutter or declutter
+ $instsecref is a reference to a hash, in which each key is
+ course num:course code, and each value is either an array of 
+ institutional sections, or (in the case of crosslisted courses)
+ an array of institutional course sections.
+
+ Returns: ok
+
+ Side effects: will modify the items in the array as determined by
+ code implemented for the domain.  Modification will differ depending
+ on whether the action is clutter or declutter.
+
+ The idea is that "clutter" will modify the name of the section such
+ that a concatenation of institutional code then (modified) section
+ will result in a string that other customized routines in localenroll.pm
+ can separate without ambiguity into instituional code then (real)
+ institutional section using a regular expression.
+
+ Conversely, "declutter" will modify the name of an already modified
+ item such that display of the concatenated string (e.g., for a 
+ crosslisting in the course catalog) does not include the "added"
+ characters used to eliminate ambiguity. 
+
+ Examples (MSU):
+
+ Starting in Fall 2021 at MSU, institution section numbers are no
+ longer guaranteed to be three digit numbers (including leading zeroes).
+
+ So, for example the course code: fs21phy183b might have sections:
+ 001, 002, LEC1, LEC2, and be crosslisted with fs21phy233b (with 
+ sections: 730, LEC3, LEC4).
+
+ The sections: LEC1, and LEC2 should be changed to _LEC1, and _LEC2
+ before creating the inner keys in the %affiliates hash of a hash,
+ passed to fetch_enrollment() in Enrollment.pm.  They will however
+ be stored in the course's environment as LEC1 and LEC2.
+
+ For the crosslistings, LEC3 and LEC4 should be changed to 
+ _LEC3 and _LEC4 before storing in the course's environment.db file.
+
+ In both cases when it comes time to extract the various components
+ of an institutional section code (i.e., the concatenated string) in
+ fetch_enrollment(), for example, the regexp used at MSU would be:
+ 
+ if ($class =~ m/^([suf]s)(\d{2})(\w{2,4})(\d{3,4}[A-Za-z]?)(\d{3}|_[A-Za-z0-9]{1,5})$/) {
+     my ($sem,$yr,$subj,$crse,$sec) = ($1,$2,$3,$4,$5);
+
+ The three digit sections would match the \d{3} and the other sections
+ (LEC1, LEC2 etc.) would match the _[A-Za-z0-9]{1,5}.
+
+ The customization in &instsec_reformat() would be:
+
+     if ($action eq 'clutter') {
+         unless ($item =~ /^\d{3}$/) {
+             $item = '_'.$item;
+         }
+     } elsif ($action eq 'declutter') {
+         if ($item =~ /^([suf]s\d{2}\w{2,4}\d{3,4}[A-Za-z]?)(\d{3}|_[A-Za-z0-9]{1,5})$/) {
+             my ($instcode,$instsec) = ($1,$2);
+             $instsec =~ s/^_//;
+             $item = $instcode.$instsec;
+         } elsif ($item =~ /^_[A-Za-z0-9]{1,5}$/) {
+             $item =~ s/^_//;
+         }
+     }
+
+=cut
+
+sub instsec_reformat {
+    my ($dom,$action,$instsecref) = @_;
+    if ((ref($instsecref) eq 'HASH') &&
+        (($action eq 'clutter') || ($action eq 'declutter'))) {
+        foreach my $key (keys(%{$instsecref})) {
+            if (ref($instsecref->{$key}) eq 'ARRAY') {
+                foreach my $sec (@{$instsecref->{$key}}) {
+                    if ($action eq 'clutter') {
+                        # modify the section, as needed.
+                        next;
+                    } elsif ($action eq 'declutter') {
+                        # modify the section, as needed.
+                        next;
+                    }
+                }
+            }
+        }
+    }
+    return 'ok';
+}
 
 =pod
 
@@ -977,6 +1072,13 @@ sub instcode_defaults {
  (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.
+ (e) $counts - reference to hash (optional), for use when called 
+               from Autoupdate.pl which can contain counts for
+               user-specified items retrieved in allusers_info()
+               or in custom subroutines which it calls. Key in
+               hashref, and count value will be printed to 
+               autoupdate.log by Autoupdate.pl.  
+                 
  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.
@@ -987,7 +1089,7 @@ sub instcode_defaults {
 =cut
 
 sub allusers_info {
-    my ($dom,$instusers,$instids,$lc_users) = @_;
+    my ($dom,$instusers,$instids,$lc_users,$counts) = @_;
     my $outcome = 'ok';
     return $outcome; 
 }
@@ -1055,7 +1157,7 @@ sub get_userinfo {
 
 =pod
 
-=item get_multusersinfo
+=item get_multusersinfo()
 
  (a) $dom - domain
  (b) $type - username or id
@@ -1148,8 +1250,8 @@ sub inst_usertypes {
                   keys of top level hash are short names  
                    (e.g., netid, noncredit) 
                   for each key, value is a hash
-                      desc => long name for rule  
-                      rule => description of rule
+                      name => long name for rule  
+                      desc => description of rule
                       authtype => (krb5,krb4,int, or loc)
                                  authentication type for rule 
                       authparm => authentication parameter for rule
@@ -1183,8 +1285,8 @@ sub username_rules {
                   keys of top level hash are short names
                    (e.g., netid, noncredit)
                   for each key, value is a hash
-                      desc => long name for rule
-                      rule => description of rule
+                      name => long name for rule
+                      desc => description of rule
 
  (c) $rulesorder - reference to array containing rule names
                    in order to be displayed
@@ -1210,8 +1312,8 @@ sub id_rules {
                   keys of top level hash are short names
                    (e.g., netid)
                   for each key, value is a hash
-                      desc => long name for rule
-                      rule => description of rule
+                      name => long name for rule
+                      desc => description of rule
 
  (c) $rulesorder - reference to array containing rule names
                    in order to be displayed
@@ -1229,6 +1331,46 @@ sub selfcreate_rules {
 
 =pod
 
+=item unamemap_rules()
+
+ Incoming data: three arguments
+ (a) $dom - domain
+ (b) $ruleshash - reference to hash containing rules
+                  (a hash of a hash)
+                  keys of top level hash are short names
+                   (e.g., netid)
+                  for each key, value is a hash
+                      name => long name for rule
+                      desc => description of rule
+
+ For example: 
+
+        %{$ruleshash} = (
+            emailaddress  => {
+                               name     => 'Email address to UserID',
+                               desc     => 'Extract userID from userID@example.tld',
+                             },
+                        );
+  would enable display of a checkbox for: 'Email address to UserID' in the
+  "Available conversions" item in the "Mapping for missing usernames via standard log-in"
+  panel available to a Domain Coordinator via:
+  Main Menu > Set domain configuration > Display ("Default authentication/language/timezone/portal/types" checked)
+
+ (c) $rulesorder - reference to array containing rule names
+                   in order to be displayed
+
+  returns 'ok' if no processing error.
+
+=cut
+
+sub unamemap_rules {
+    my ($dom,$ruleshash,$rulesorder) = @_;
+    my $outcome;
+    return $outcome;
+}
+
+=pod
+
 =item username_check() 
 
  Incoming data: four arguments
@@ -1236,7 +1378,7 @@ sub selfcreate_rules {
  (b) $uname - username to compare against rules (scalar)
  (c) $to_check (reference to array of rule names to check)
  (d) $resultshash (reference to hash of results)
-                    hash of results for rule checked
+                    hash of results for rules checked
                    - keys are rule names
                    - values are: 1 or 0 (for matched or unmatched) 
 
@@ -1260,7 +1402,7 @@ sub username_check {
  (b) $id - ID to compare against rules (scalar)
  (c) $to_check (reference to array of rule names to check)
  (d) $resultshash (reference to hash of results)
-                    hash of results for rule checked
+                    hash of results for rules checked
                    - keys are rule names
                    - values are: 1 or 0 (for matched or unmatched)
 
@@ -1284,7 +1426,7 @@ sub id_check {
  (b) $selfcreatename - e-mail proposed as username (compare against rules - scalar)
  (c) $to_check (reference to array of rule names to check)
  (d) $resultshash (reference to hash of results)
-                   hash of results for rule checked
+                   hash of results for rules checked
                    - keys are rule names
                    - values are: 1 or 0 (for matched or unmatched)
 
@@ -1298,6 +1440,44 @@ sub selfcreate_check {
     my $outcome;
     return $outcome;
 }
+
+=pod
+
+=item unamemap_check()
+
+ Incoming data: four arguments
+ (a) $dom - domain (scalar)
+ (b) $uname - username entered on log-in page (compare against rules - scalar)
+ (c) $to_check (reference to array of rule names to check)
+ (d) $resultshash (reference to hash of results)
+                   hash of results for rules checked
+                   - keys are rule names
+                   - values are derived username from substitution operation
+                     applied to $uname.
+
+  For example, in the msu domain the rule "msuemail" will replace an MSU
+  email address submitted as a username, with the part before the @msu.edu,
+  (known as the MSUNetID), which is what is used in LON-CAPA as a username.
+
+  if ($dom eq 'msu') {
+      foreach my $item (@{$to_check}) {
+          if ($item eq 'msuemail') {
+              if ($uname =~ /^(\w{2,8})\@msu\.edu$/) {
+                  $resultshash->{$item} = $1;
+              }
+          }
+      }
+   }
+
+ returns 'ok' if no processing error.
+
+=cut
+
+sub unamemap_check {
+    my ($dom,$uname,$to_check,$resultshash) = @_;
+    my $outcome;
+    return $outcome;
+}
 
 =pod