--- loncom/enrollment/localenroll.pm	2009/02/20 13:59:20	1.33
+++ loncom/enrollment/localenroll.pm	2009/09/13 03:14:12	1.39
@@ -1,6 +1,6 @@
 # functions to glue school database system into Lon-CAPA for 
 # automated enrollment
-# $Id: localenroll.pm,v 1.33 2009/02/20 13:59:20 bisitz Exp $
+# $Id: localenroll.pm,v 1.39 2009/09/13 03:14:12 raeburn Exp $
 #
 # Copyright Michigan State University Board of Trustees
 #
@@ -41,8 +41,6 @@ described at http://www.lon-capa.org.
 
 =over
 
-=back
-
 =cut
 
 package localenroll;
@@ -281,6 +279,142 @@ sub validate_courseID {
 
 =pod
 
+=item validate_instcode()
+
+This is called when a request is being made for an official course.
+A check is made that the institutional code for which a course is
+is being requested is valid according to the institutional
+schedule of official classes.
+
+If the username of the course owner is provided, a more restrictive
+test is used, namely that the requestor is listed as instructor of
+record for the course in the institution's course schedule/database.
+
+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.
+
+An array is returned containing (a) the result of the check for a valid 
+instcode, and (b) an (optional) course description.   
+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) = @_;
+    my $outcome = '';
+    my $description = '';
+    return ($outcome,$description);
+}
+
+=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 six 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).
+
+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) 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 in a 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).
+
+=cut
+
+sub validate_crsreq {
+    my ($dom,$owner,$crstype,$inststatuslist,$instcode,$instseclist) = @_;
+    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, $reqtyes, $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 create_password()
 
  This is called when the authentication method set for the automated 
@@ -381,6 +515,43 @@ sub instcode_format () {
     return $outcome;
 }
 
+=pod
+
+=item possible_instcodes()
+
+Gather acceptable values for institutional categories to use in course creation request form for official courses.
+
+ requires four 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).
+
+ e.g., 
+ @{$codetitles} = ("Year","Semester","Department","Number");
+
+ %{$$cat_titles{'Semester'}} = (
+                   fs => 'Fall',
+                   ss => 'Spring',
+                   us => 'Summer');
+
+ @{$$cat_order{'Semester'}} = ('ss','us','fs');
+
+ returns 1 parameter: 'ok' if no processing errors.
+
+=cut
+
+sub possible_instcodes {
+    my ($dom,$codetitles,$cat_titles,$cat_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);
+    return 'ok';
+}
+
+
 
 =pod
 
@@ -401,7 +572,7 @@ sub instcode_format () {
      existing photo, photo was found to be missing from institution's
      data store, photo used is same as before, or photo was 
      deleted from storage on LON-CAPA server housing student's
-     information, no student ID was available. 
+     information, no student/employee ID was available. 
                
  (e) $action: the type of action needed. (e.g., update, delete);
  (f) $students: a reference to a hash with the keys set to student