--- loncom/enrollment/localenroll.pm	2014/06/26 15:53:29	1.50
+++ 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.50 2014/06/26 15:53:29 raeburn Exp $
+# $Id: localenroll.pm,v 1.53 2015/08/05 18:47:17 raeburn Exp $
 #
 # Copyright Michigan State University Board of Trustees
 #
@@ -358,7 +358,7 @@ 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)
@@ -369,21 +369,27 @@ validate_crsreq takes six arguments -
  (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().
+     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
@@ -444,6 +450,42 @@ sub crsreq_checks {
     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) = @_;
@@ -893,6 +935,47 @@ sub get_userinfo {
     return $outcome;
 }
 
+=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()