[BACK]Return to localenroll.pm CVS log [TXT] [DIR] Up to [LON-CAPA] / loncom / enrollment

Diff for /loncom/enrollment/localenroll.pm between versions 1.31 and 1.32

version 1.31, 2008/02/29 21:01:43 version 1.32, 2008/11/25 13:16:26
Line 24 Line 24
 #  #
 # http://www.lon-capa.org/  # http://www.lon-capa.org/
 #  #
   
   =pod
   
   =head1 NAME
   
   localenroll
   
   =head1 SYNOPSIS
   
   This is part of the LearningOnline Network with CAPA project
   described at http://www.lon-capa.org.
   
   
   =head1 NOTABLE SUBROUTINES
   
   =over
   
   =back
   
   =cut
   
 package localenroll;  package localenroll;
   
 use strict;  use strict;
   
 ################################  =pod
 # sub run   
 # set this to return 1 if you want the auto enrollment to run  =item run()
 #   set this to return 1 if you want the auto enrollment to run
 # Beginning with LON-CAPA version 2.4, use of this routine is  
 # deprecated.  Whether or not Autoenroll.pl should run is set   Beginning with LON-CAPA version 2.4, use of this routine is
 # by the Domain Coordinator via "Set domain configuration",   deprecated.  Whether or not Autoenroll.pl should run is set
 # provided in the Domain Management section of the Main menu.    by the Domain Coordinator via "Set domain configuration",
 ################################   provided in the Domain Management section of the Main menu. 
   
   =cut
   
 sub run() {  sub run() {
     my $dom = shift;      my $dom = shift;
     return 0;      return 0;
 }  }
   
 ################################  
 # sub fetch_enrollment  =pod
 #  
 # connects to the institutional classlist data source,  =item fetch_enrollment()
 # reads classlist data and stores in an XML file  
 # in /home/httpd/perl/tmp/   connects to the institutional classlist data source,
 #   reads classlist data and stores in an XML file
 # classlist files are named as follows:   in /home/httpd/perl/tmp/
 #  
 # DOMAIN_COURSE_INSTITUTIONALCODE_classlist.xml   classlist files are named as follows:
 #  
 # e.g., msu_43551dedcd43febmsul1_fs03nop590001_classlist.xml   DOMAIN_COURSE_INSTITUTIONALCODE_classlist.xml
 # where DOMAIN = msu  COURSE = 43551dedcd43febmsul1   
 # INSTITUTIONALCODE = fs03nop590001    e.g., msu_43551dedcd43febmsul1_fs03nop590001_classlist.xml
 # (MSU's course naming scheme - fs03 = Fall semester 2003, nop =   where DOMAIN = msu  COURSE = 43551dedcd43febmsul1 
 # department name, 590 = course number, 001 = section number.)   INSTITUTIONALCODE = fs03nop590001 
 #   (MSU's course naming scheme - fs03 = Fall semester 2003, nop =
 # fetch_enrollment requires three arguments -   department name, 590 = course number, 001 = section number.)
 # $dom - DOMAIN e.g., msu  
 # $affiliatesref - a reference to a hash of arrays that contains LON-CAPA    fetch_enrollment requires three arguments -
 # courses that are to be updated as keys, and institutional coursecodes    $dom - DOMAIN e.g., msu
 # contributing enrollment to that LON-CAPA course as elements in each array.   $affiliatesref - a reference to a hash of arrays that contains LON-CAPA 
 # $replyref - a reference to a hash that contains LON-CAPA courses   courses that are to be updated as keys, and institutional coursecodes 
 # that are to be updated as keys, and the total enrollment count in all    contributing enrollment to that LON-CAPA course as elements in each array.
 # affiliated sections, as determined from institutional data as hash elements.    $replyref - a reference to a hash that contains LON-CAPA courses
 #   that are to be updated as keys, and the total enrollment count in all 
 # As an example, if fetch_enrollment is called to retrieve institutional   affiliated sections, as determined from institutional data as hash elements. 
 # classlists for a single LON-CAPA course - 43551dedcd43febmsul1 which   
 # corresponds to fs03nop590, sections 001, 601 and 602 , and the course   As an example, if fetch_enrollment is called to retrieve institutional
 # also accommodates enrollment from a crosslisted course in the ost   classlists for a single LON-CAPA course - 43551dedcd43febmsul1 which 
 # department - fs03ost580002:   corresponds to fs03nop590, sections 001, 601 and 602 , and the course
 #   also accommodates enrollment from a crosslisted course in the ost
 # the affiliatesref would be a reference to %affiliates which would be:   department - fs03ost580002:
 #  
 # @{$affiliates{'43551dedcd43febmsul1'}} =   the affiliatesref would be a reference to %affiliates which would be:
 #   ("fs03nop590001","fs03nop590601","fs03nop590602","fs03ost580002");  
 #   @{$affiliates{'43551dedcd43febmsul1'}} =
 # fetch_enrollment would create four files in /home/httpd/perl/tmp/.     ("fs03nop590001","fs03nop590601","fs03nop590602","fs03ost580002");
 # msu_43551dedcd43febmsul1_fs03nop590001_classlist.xml  
 # msu_43551dedcd43febmsul1_fs03nop590601_classlist.xml   fetch_enrollment would create four files in /home/httpd/perl/tmp/.
 # msu_43551dedcd43febmsul1_fs03nop590602_classlist.xml   msu_43551dedcd43febmsul1_fs03nop590001_classlist.xml
 # msu_43551dedcd43febmsul1_fs03ost580002_classlist.xml   msu_43551dedcd43febmsul1_fs03nop590601_classlist.xml
 #   msu_43551dedcd43febmsul1_fs03nop590602_classlist.xml
 # In each file, student data would be stored in the following format   msu_43551dedcd43febmsul1_fs03ost580002_classlist.xml
 #   
 # <student username="smith">   In each file, student data would be stored in the following format
 #  <autharg>MSU.EDU</autharg>   
 #  <authtype>krb4</authtype>   <student username="smith">
 #  <email>smith@msu.edu</email>    <autharg>MSU.EDU</autharg>
 #  <enddate></enddate>    <authtype>krb4</authtype>
 #  <firstname>John</firstname>    <email>smith@msu.edu</email>
 #  <generation>II</generation>    <enddate></enddate>
 #  <groupID>fs03nop590001</groupID>    <firstname>John</firstname>
 #  <lastname>Smith</lastname>    <generation>II</generation>
 #  <middlename>D</middlename>    <groupID>fs03nop590001</groupID>
 #  <startdate></startdate>    <lastname>Smith</lastname>
 #  <studentID>A12345678</studentID>    <middlename>D</middlename>
 # </student>    <startdate></startdate>
 #     <studentID>A12345678</studentID>
 # with the following at the top of the file   </student>
 #<?xml version="1.0" encoding="UTF-8"?>   
 #<!DOCTYPE text>   with the following at the top of the file
 #<students>  <?xml version="1.0" encoding="UTF-8"?>
 #  <!DOCTYPE text>
 # (all comment - #s removed)  <students>
 #  
 # and a closing:   (all comment - s removed)
 #</students>  
 #   and a closing:
 # The <startdate> and the <enddate> are the activation date and expiration date  </students>
 # for this student's role. If they are absent, then the default access start and  
 # default access end dates are used. The default access dates can be set when    The <startdate> and the <enddate> are the activation date and expiration date
 # the course is created, and can be modified using the Automated Enrollment   for this student's role. If they are absent, then the default access start and
 # Manager, or via the 'Upload a class list','Enroll a single student' or    default access end dates are used. The default access dates can be set when 
 # 'Modify student data' utilities in the Enrollment Manager, by checking the    the course is created, and can be modified using the Automated Enrollment
 # 'make these dates the default for future enrollment' checkbox. If no default    Manager, or via the 'Upload a class list','Enroll a single student' or 
 # dates have been set, then the tudent role will be active immediately, and will    'Modify student data' utilities in the Enrollment Manager, by checking the 
 # remain active until the role is explicitly expired using ENRL -> Drop students.    'make these dates the default for future enrollment' checkbox. If no default 
 # If dates are to included in the XML file, they should be in the format   dates have been set, then the tudent role will be active immediately, and will 
 # YYYY:MM:DD:HH:MM:SS (: separators required).   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
 # If there were 10 students in fs03nop590001, 5 students in fs03nop59o601,    YYYY:MM:DD:HH:MM:SS (: separators required).
 # 8 students in fs03nop590602, and 2 students in fs03ost580002,  
 # then $$reply{'43551dedcd43febmsul1'} = 25   If there were 10 students in fs03nop590001, 5 students in fs03nop59o601, 
 #   8 students in fs03nop590602, and 2 students in fs03ost580002,
 # The purpose of the %reply hash is to detect cases where the institutional    then $$reply{'43551dedcd43febmsul1'} = 25
 # enrollment is 0 (most likely due to a problem with the data source).  
 # In such a case, the LON-CAPA course roster is left unchanged (i.e., no   The purpose of the %reply hash is to detect cases where the institutional 
 # students are expired, even if automated drops is enabled.   enrollment is 0 (most likely due to a problem with the data source).
 #    In such a case, the LON-CAPA course roster is left unchanged (i.e., no
 # fetch_enrollment should return a 0 or 1, depending on whether a connection   students are expired, even if automated drops is enabled.
 # could be established to the institutional data source.   
 # 0 is returned if no connection could be made.   fetch_enrollment should return a 0 or 1, depending on whether a connection
 # 1 is returned if connection was successful   could be established to the institutional data source.
 #   0 is returned if no connection could be made.
 # A return of 1 is required for the calling modules to perform LON-CAPA   1 is returned if connection was successful
 # roster changes based on the contents of the XML classlist file(s), e,g,,  
 # msu_43551dedcd43febmsul1_fs03nop590001_classlist.xml   A return of 1 is required for the calling modules to perform LON-CAPA
 #   roster changes based on the contents of the XML classlist file(s), e,g,,
 # XML classlist files are temporary. They are deleted after the enrollment    msu_43551dedcd43febmsul1_fs03nop590001_classlist.xml
 # update process in the calling module is complete.  
 #   XML classlist files are temporary. They are deleted after the enrollment 
 ################################   update process in the calling module is complete.
   
   
   =cut
   
 sub fetch_enrollment {  sub fetch_enrollment {
     my ($dom,$affiliatesref,$replyref) = @_;      my ($dom,$affiliatesref,$replyref) = @_;
Line 156  sub fetch_enrollment { Line 182  sub fetch_enrollment {
     return $okflag;      return $okflag;
 }  }
   
 ###############################  =pod
 # sub get_sections  
 #  =item get_sections()
 # This is called by the Automated Enrollment Manager interface  
 # (lonpopulate.pm) to create an array of valid sections for    This is called by the Automated Enrollment Manager interface
 # a specific institutional coursecode.   (lonpopulate.pm) to create an array of valid sections for 
 # e.g., for MSU coursecode: fs03nop590   a specific institutional coursecode.
 # ("001","601","602") would be returned   e.g., for MSU coursecode: fs03nop590
 #   ("001","601","602") would be returned
 # If the array returned contains at least one element, then   
 # the interface offerred to the course coordinator, lists   If the array returned contains at least one element, then 
 # official sections and provides a checkbox to use to   the interface offerred to the course coordinator, lists
 # select enrollment in the LON-CAPA course from each official section.     official sections and provides a checkbox to use to
 #   select enrollment in the LON-CAPA course from each official section.  
 # get_sections takes two arguments - (a) the institutional coursecode  
 # (in the MSU case this is a concatenation of semester code, department   get_sections takes two arguments - (a) the institutional coursecode
 # and course number), and (b) the LON-CAPA domain that contains the course.    (in the MSU case this is a concatenation of semester code, department
 #    and course number), and (b) the LON-CAPA domain that contains the course. 
 # If there is no access to official course sections at your institution,   
 # then an empty array is returned, and the Automated Enrollment Manager   If there is no access to official course sections at your institution,
 # interface will allow the course coordinator to enter section numbers   then an empty array is returned, and the Automated Enrollment Manager
 # in text boxes.   interface will allow the course coordinator to enter section numbers
 #    in text boxes.
 ###############################   
   
   
   =cut
   
 sub get_sections {  sub get_sections {
     my ($coursecode,$dom) = @_;      my ($coursecode,$dom) = @_;
Line 187  sub get_sections { Line 216  sub get_sections {
     return @secs;      return @secs;
 }  }
   
 ###############################  =pod
 # sub new_course  
 #  =item new_course()
 # This is called by loncreatecourse.pm and   
 # lonpopulate.pm to record that fact that a new course section   This is called by loncreatecourse.pm and 
 # has been added to LON-CAPA that requires access to institutional data   lonpopulate.pm to record that fact that a new course section
 # At MSU, this is required, as institutional classlists can only made   has been added to LON-CAPA that requires access to institutional data
 # available to faculty who are officially assigned to a course.   At MSU, this is required, as institutional classlists can only made
 #    available to faculty who are officially assigned to a course.
 # The new_course subroutine is used to check that the course owner   
 # of the LON-CAPA course is permitted to access the institutional   The new_course subroutine is used to check that the course owner
 # classlist for any course sections and crosslisted classes that   of the LON-CAPA course is permitted to access the institutional
 # the course coordinator wishes to have affiliated with the course.   classlist for any course sections and crosslisted classes that
 #    the course coordinator wishes to have affiliated with the course.
 # If access is permitted, then 'ok' is returned.   
 # The course section or crosslisted course will only be added to the list of   If access is permitted, then 'ok' is returned.
 # affiliates if 'ok' is returned.   The course section or crosslisted course will only be added to the list of
 #   affiliates if 'ok' is returned.
 # new_course takes three arguments -  
 # (a) the institutional courseID (in the MSU case this is a concatenation of    new_course takes three arguments -
 # semester code, department code, course number, and section number   (a) the institutional courseID (in the MSU case this is a concatenation of 
 # e.g., fs03nop590001).   semester code, department code, course number, and section number
 # (b) the course owner. This is the LON-CAPA username and domain of the course    e.g., fs03nop590001).
 # coordinator assigned to the course when it is first created, in the form   (b) the course owner. This is the LON-CAPA username and domain of the course 
 # username:domain   coordinator assigned to the course when it is first created, in the form
 # (c) the LON-CAPA domain that contains the course   username:domain
 #   (c) the LON-CAPA domain that contains the course
 #################################  
   =cut
   
 sub new_course  {  sub new_course  {
     my ($course_id,$owner,$dom) = @_;      my ($course_id,$owner,$dom) = @_;
Line 222  sub new_course  { Line 252  sub new_course  {
     return $outcome;      return $outcome;
 }  }
   
 ###############################  =pod
 # sub validate_courseID  
 #  =item validate_courseID()
 # This is called whenever a new course section or crosslisted course  
 # is being affiliated with a LON-CAPA course (i.e., by loncreatecourse.pm   This is called whenever a new course section or crosslisted course
 # and the Automated Enrollment Manager in lonpopulate.pm).   is being affiliated with a LON-CAPA course (i.e., by loncreatecourse.pm
 # A check is made that the courseID that the course coordinator wishes   and the Automated Enrollment Manager in lonpopulate.pm).
 # to affiliate with the course is valid according to the institutional   A check is made that the courseID that the course coordinator wishes
 # schedule of official classes    to affiliate with the course is valid according to the institutional
 #   schedule of official classes 
 # A valid courseID is confirmed by returning 'ok'  
 #   A valid courseID is confirmed by returning 'ok'
 # validate_courseID takes two arguments -  
 # (a) the institutional courseID (in the MSU case this is a concatenation of   validate_courseID takes two arguments -
 # semester code, department code, course number, and section number   (a) the institutional courseID (in the MSU case this is a concatenation of
 # e.g., fs03nop590001).   semester code, department code, course number, and section number
 # (b) the LON-CAPA domain that contains the course   e.g., fs03nop590001).
 #   (b) the LON-CAPA domain that contains the course
 ###############################    
   =cut  
   
 sub validate_courseID {  sub validate_courseID {
     my ($course_id,$dom) = @_;      my ($course_id,$dom) = @_;
Line 248  sub validate_courseID { Line 279  sub validate_courseID {
     return $outcome;         return $outcome;   
 }  }
   
 ###############################  =pod
 # sub create_password   
 #  =item create_password()
 # This is called when the authentication method set for the automated   
 # enrollment process when enrolling new users in the domain is "localauth".   This is called when the authentication method set for the automated 
 # This could be signalled for the specific user by the value of localauth   enrollment process when enrolling new users in the domain is "localauth".
 # for the <authtype> tag from the classlist.xml files, or if this is blank,   This could be signalled for the specific user by the value of localauth
 # the default authtype, set by the domain coordinator when creating the course   for the <authtype> tag from the classlist.xml files, or if this is blank,
 # with loncreatecourse.pm.   the default authtype, set by the domain coordinator when creating the course
 #     with loncreatecourse.pm.
 # create_password takes three arguments -    
 # (a) $authparam - the value of <autharg> from the classlist.xml files,   create_password takes three arguments -
 # or if this blank, the default autharg, set by the domain coordinator when    (a) $authparam - the value of <autharg> from the classlist.xml files,
 # creating the course with loncreatecourse.pm   or if this blank, the default autharg, set by the domain coordinator when 
 # (b) $dom - the domain of the new user.   creating the course with loncreatecourse.pm
 # (c) $username - the username of the new user (currently not actually used)   (b) $dom - the domain of the new user.
 #   (c) $username - the username of the new user (currently not actually used)
 # Four values are returned:  
 # (a) the value of $authparam - which might have been changed   Four values are returned:
 # (b) a flag to indicate whether a password had been created   (a) the value of $authparam - which might have been changed
 # 0 means no password created   (b) a flag to indicate whether a password had been created
 # 1 means password created.  In this case the calling module - Enrollment.pm   0 means no password created
 # will send the LON-CAPA username and password to the new user's e-mail   1 means password created.  In this case the calling module - Enrollment.pm
 # (if one was provided), or to the course owner (if one was not provided and   will send the LON-CAPA username and password to the new user's e-mail
 # the new user was created by the automated process), or to the active   (if one was provided), or to the course owner (if one was not provided and
 # course coordinator (if the new user was created using the 'update roster   the new user was created by the automated process), or to the active
 # now' interface included in the Automated Enrollment Manager).     course coordinator (if the new user was created using the 'update roster
 # (c) a flag to indicate that the authentication method is correct - 'ok'.   now' interface included in the Automated Enrollment Manager).  
 # If $authchk is not set to 'ok' then account creation and enrollment of the    (c) a flag to indicate that the authentication method is correct - 'ok'.
 # new user will not occur.   If $authchk is not set to 'ok' then account creation and enrollment of the 
 # (d) if a password was created it can be sent along.  This is the password    new user will not occur.
 # which will be included in the e-mail sent to the new user, or made available       (d) if a password was created it can be sent along.  This is the password 
 # to the course owner/course coordinator if no e-mail address is provided. If   which will be included in the e-mail sent to the new user, or made available    
 # you do not wish to send a password, but want to give instructions on obtaining   to the course owner/course coordinator if no e-mail address is provided. If
 # one, you could set $newpasswd as those instructions. (e.g.,   you do not wish to send a password, but want to give instructions on obtaining
 # $newpasswd = '(Please visit room 212, ACNS Bldg. to obtain your password)';   one, you could set $newpasswd as those instructions. (e.g.,
 # The value of $newpasswd is NOT written in the user's LON-CAPA passwd file in   $newpasswd = '(Please visit room 212, ACNS Bldg. to obtain your password)';
 # /home/httpd/lonUsers/$dom/a/b/c/abcuser/passwd, which in the case of a user   The value of $newpasswd is NOT written in the user's LON-CAPA passwd file in
 # employing localauth will contain 'localauth:$authparam'.  If you need to include   /home/httpd/lonUsers/$dom/a/b/c/abcuser/passwd, which in the case of a user
 # a parameter in the user's passwd file, you should return it as $authparam,   employing localauth will contain 'localauth:$authparam'.  If you need to include
 # i.e., the first of the variables returned by create_password().                a parameter in the user's passwd file, you should return it as $authparam,
 ###############################   i.e., the first of the variables returned by create_password().             
   
   
   =cut 
   
 sub create_password {  sub create_password {
     my ($authparam,$dom,$username) = @_;      my ($authparam,$dom,$username) = @_;
Line 299  sub create_password { Line 333  sub create_password {
     return ($authparam,$create_passwd,$authchk,$newpasswd);      return ($authparam,$create_passwd,$authchk,$newpasswd);
 }  }
   
 ###############################  =pod
 # sub instcode_format   
 #  =item instcode_format()
 # Split coursecodes into constituent parts.     
 # e.g., INSTITUTIONALCODE = fs03nop590, LON-CAPA COURSEID: 43551dedcd43febmsul1   Split coursecodes into constituent parts.   
 # (MSU's course naming scheme - fs03 = Fall semester 2003, nop =   e.g., INSTITUTIONALCODE = fs03nop590, LON-CAPA COURSEID: 43551dedcd43febmsul1
 # department name, 590 = course number)   (MSU's course naming scheme - fs03 = Fall semester 2003, nop =
 #   department name, 590 = course number)
 # Incoming data:  
 # $dom (domain)   Incoming data:
 # $$instcodes{'43551dedcd43febmsul1'} = 'fs03nop590' (hash of courseIDs)   $dom (domain)
 #    $$instcodes{'43551dedcd43febmsul1'} = 'fs03nop590' (hash of courseIDs)
 # fs03nop590 would be split as follows   
 # @{$codetitles} = ("year","semester","department","number")   fs03nop590 would be split as follows
 # $$codes{{'year'} = '2003'   @{$codetitles} = ("year","semester","department","number")
 # $$codes{'semester'} = 'Fall'   $$codes{{'year'} = '2003'
 # $$codes{'department'} = 'nop'   $$codes{'semester'} = 'Fall'
 # $$codes{'number'} = '590'   $$codes{'department'} = 'nop'
 #   $$codes{'number'} = '590'
 # requires six arguments:  
 # domain ($dom)   requires six arguments:
 # reference to hash of institutional course IDs ($instcodes)     domain ($dom)
 # reference to hash of codes ($codes)   reference to hash of institutional course IDs ($instcodes)  
 # reference to array of titles ($codetitles)   reference to hash of codes ($codes)
 # reference to hash of abbreviations used in categories   reference to array of titles ($codetitles)
 # reference to hash of arrays specifying sort order used in category titles      reference to hash of abbreviations used in categories
 #   reference to hash of arrays specifying sort order used in category titles   
 # e.g.,     %{$$cat_titles{'Semester'}} = (  
 #                   fs => 'Fall',   e.g.,     %{$$cat_titles{'Semester'}} = (
 #                   ss => 'Spring',                     fs => 'Fall',
 #                   us => 'Summer');                     ss => 'Spring',
 #                     us => 'Summer');
 # e.g., @{$$cat_order{'Semester'}} = ('ss','us','fs');   
 # returns 1 parameter: 'ok' if no processing errors.     e.g., @{$$cat_order{'Semester'}} = ('ss','us','fs'); 
 ###############################   returns 1 parameter: 'ok' if no processing errors. 
    
   =cut
   
   
 sub instcode_format () {  sub instcode_format () {
     my ($dom,$instcodes,$codes,$codetitles,$cat_titles,$cat_order) = @_;      my ($dom,$instcodes,$codes,$codetitles,$cat_titles,$cat_order) = @_;
Line 341  sub instcode_format () { Line 378  sub instcode_format () {
     return $outcome;      return $outcome;
 }  }
   
 ###############################  
 # sub institutional_photos  =pod
 #  
 # Called when automated enrollment manager is used to update student photos.  =item institutional_photos()
 #  
 # Incoming data: six arguments   Called when automated enrollment manager is used to update student photos.
 # (a) $dom (domain)  
 # (b) $crs (LONCAPA course number)   Incoming data: six arguments
 # (c) $affiliates: a reference to a hash with the keys set to the    (a) $dom (domain)
 # institutional course IDs for the course.   (b) $crs (LONCAPA course number)
 # (d) $result: a reference to a hash which will return usernames     (c) $affiliates: a reference to a hash with the keys set to the 
 #     of students (& separated) in following categories (the keys):   institutional course IDs for the course.
 #     new, update, missing, same, deleted, noid, nouser. The list    (d) $result: a reference to a hash which will return usernames  
 #     includes those students for whom the result of the modification        of students (& separated) in following categories (the keys):
 #     process was either addition of a new photo. update of an       new, update, missing, same, deleted, noid, nouser. The list 
 #     existing photo, photo was found to be missing from institution's       includes those students for whom the result of the modification 
 #     data store, photo used is same as before, or photo was        process was either addition of a new photo. update of an
 #     deleted from storage on LON-CAPA server housing student's       existing photo, photo was found to be missing from institution's
 #     information, no student ID was available.        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. 
                                 
 # (e) $action: the type of action needed. (e.g., update, delete);   (e) $action: the type of action needed. (e.g., update, delete);
 # (f) $students: a reference to a hash with the keys set to student    (f) $students: a reference to a hash with the keys set to student 
 # usernames and domains in the form username:domain, and values set   usernames and domains in the form username:domain, and values set
 # to the studentID, if action is required for specific students.     to the studentID, if action is required for specific students.  
 #  
 # returns 1 parameter: 'ok' if no processing errors.   returns 1 parameter: 'ok' if no processing errors.
 # other course or student specific values can be stored as values   other course or student specific values can be stored as values
 # in the appropriate referenced hashes.    in the appropriate referenced hashes. 
 ###############################  
   =cut
   
 sub institutional_photos {  sub institutional_photos {
     my ($dom,$crs,$affiliates,$result,$action,$students) = @_;      my ($dom,$crs,$affiliates,$result,$action,$students) = @_;
Line 377  sub institutional_photos { Line 417  sub institutional_photos {
     return $outcome;      return $outcome;
 }  }
   
 ###############################  =pod
 # sub photo_permission  
 #  =item photo_permission()
 # Incoming data: three arguments  
 # (a) $dom (domain)   Incoming data: three arguments
 # (b) $perm_reqd: a reference to a a scalar that is either 'yes'   (a) $dom (domain)
 # if a course owner must indicate acceptance of conditions of use,   (b) $perm_reqd: a reference to a a scalar that is either 'yes'
 # 'no' otherwise.   if a course owner must indicate acceptance of conditions of use,
 # (c) $conditions: the text of the conditions of use.   'no' otherwise.
 #       (c) $conditions: the text of the conditions of use.
 # returns 1 parameter: 'ok' if no processing errors.      
 # $$perm_reqd is set to 'yes' or 'no'   returns 1 parameter: 'ok' if no processing errors.
 # $$agreement is set to conditions of use - plain text string   $$perm_reqd is set to 'yes' or 'no'
 #             which will be displayed in a textarea in a web form.   $$agreement is set to conditions of use - plain text string
 ###############################               which will be displayed in a textarea in a web form.
    
   
   =cut
   
 sub photo_permission {  sub photo_permission {
    my ($dom,$perm_reqd,$conditions) = @_;     my ($dom,$perm_reqd,$conditions) = @_;
    $$perm_reqd = 'no';     $$perm_reqd = 'no';
Line 401  sub photo_permission { Line 444  sub photo_permission {
    return $outcome;     return $outcome;
 }  }
   
   =pod
   
 ###############################  =item manager_photo_update()
 # sub manager_photo_update  
 #   Incoming data: one argument
 # Incoming data: one argument   (a) $dom (domain)
 # (a) $dom (domain)  
 #   returns 2 parameters: update (0 or 1), and comment.
 # returns 2 parameters: update (0 or 1), and comment.   Called by automated enrollment manager, to determine 
 # Called by automated enrollment manager, to determine    whether "Update Student photos" button will be available,
 # whether "Update Student photos" button will be available,   and if so, the message (plain text string) that will be displayed
 # and if so, the message (plain text string) that will be displayed   with the button. 
 # with the button.   
 ###############################  
   =cut
                                                                                                                                                                                   
 sub manager_photo_update {  sub manager_photo_update {
     my ($dom) = @_;      my ($dom) = @_;
Line 422  sub manager_photo_update { Line 467  sub manager_photo_update {
     return ($update,$comment);      return ($update,$comment);
 }  }
   
 ###############################  =pod
 # sub check_section  
 #  
 # Incoming data: three arguments (+ fourth optional argument)  =item check_section()
 # (a) $class - institutional class id (coursecode concatanated with section)   
 # (b) $owner - course owner (2.2 and later username:domain; pre-2.2 username;   Incoming data: three arguments (+ fourth optional argument)
 #                            2.6 and later - comma-separated list of    (a) $class - institutional class id (coursecode concatanated with section) 
 #                            username:domain for course owner and co-owners.)   (b) $owner - course owner (2.2 and later username:domain; pre-2.2 username;
 # (c) $dom - domain of course                              2.6 and later - comma-separated list of 
 # (d) $dbh - optional database handle                              username:domain for course owner and co-owners.)
 #   (c) $dom - domain of course
 # returns 1 parameter - $sectioncheck ('ok' or other value).    (d) $dbh - optional database handle
 # Verifies that at least one of the course owner (or co-owners) have access   
 # to classlist for specific class according to institution's SIS   returns 1 parameter - $sectioncheck ('ok' or other value). 
 # 'ok' if access available     Verifies that at least one of the course owner (or co-owners) have access 
 ###############################   to classlist for specific class according to institution's SIS
    'ok' if access available  
   
   
   =cut
   
 sub check_section {  sub check_section {
     my ($class,$owner,$dom,$dbh) = @_;      my ($class,$owner,$dom,$dbh) = @_;
Line 445  sub check_section { Line 494  sub check_section {
     return $sectioncheck;      return $sectioncheck;
 }  }
   
 ###############################  =pod
 # sub instcode_defaults  
 #  =item instcode_defaults()
 # Incoming data: three arguments  
 # (a) $dom - domain   Incoming data: three arguments
 # (b) $defaults - reference to hash which will contain default regular   (a) $dom - domain
 #                 expression matches for different components of an    (b) $defaults - reference to hash which will contain default regular
 #                 institutional course code                    expression matches for different components of an 
 # (c) $code_order - reference to array which will contain order of                    institutional course code 
 #                   component parts used in institutional code.     (c) $code_order - reference to array which will contain order of 
 #                     component parts used in institutional code.  
 # returns 1 parameter - ('ok' or other value).  
 # Used to construct a regular expression to be used when searching for   returns 1 parameter - ('ok' or other value).
 # courses based on fragments of an institutional code.   Used to construct a regular expression to be used when searching for
 # $defaults contains defaults to use for each component, and code_order   courses based on fragments of an institutional code.
 # contains keys of hash in order in which they are to be concatenated.   $defaults contains defaults to use for each component, and code_order
 #   contains keys of hash in order in which they are to be concatenated.
 # e.g., INSTITUTIONALCODE = fs03nop590  
 # (MSU's course naming scheme - fs  = semester, 03 = year, nop =   e.g., INSTITUTIONALCODE = fs03nop590
 # department name, 590 = course number)   (MSU's course naming scheme - fs  = semester, 03 = year, nop =
 #   department name, 590 = course number)
 #     %{$defaults} = (  
 #        'Year' => '\d{2}',       %{$defaults} = (
 #        'Semester' => '^[sfu]s',           'Year' => '\d{2}',
 #        'Department' => '\w{2,3}',          'Semester' => '^[sfu]s', 
 #        'Number' => '\d{3,4}\w?',          'Department' => '\w{2,3}',
 #     );          'Number' => '\d{3,4}\w?',
 #       );
 #     @{$code_order} = ('Semester','Year','Department','Number');  
 #       @{$code_order} = ('Semester','Year','Department','Number');
 ###############################  
   =cut
   
 sub instcode_defaults {  sub instcode_defaults {
     my ($dom,$defaults,$code_order) = @_;      my ($dom,$defaults,$code_order) = @_;
     return 'ok';      return 'ok';
 }  }
   
 ###############################  
 # sub allusers_info  =pod
 #  
 # Incoming data: three arguments  =item allusers_info()
 # (a) $dom - domain  
 # (b) $instusers - reference to hash which will contain hashes,    Incoming data: three arguments
 #                 where keys will be usernames and value will be a    (a) $dom - domain
 #                 hash of user information. Keys in the inner hash    (b) $instusers - reference to hash which will contain hashes, 
 #                 will be some or all of: lastname,firstname,                   where keys will be usernames and value will be a 
 #                 middlename, generation, id, inststatus -                    hash of user information. Keys in the inner hash 
 #                 institutional status (e.g., faculty,staff,student)                   will be some or all of: lastname,firstname,
 #                 Values are all scalars except inststatus,                   middlename, generation, id, inststatus - 
 #                 which is an array.                   institutional status (e.g., faculty,staff,student)
 # (c) $instids - reference to hash which will contain ID numbers.                    Values are all scalars except inststatus,
 #                keys will be unique IDs (student or faculty/staff ID)                   which is an array.
 #                values will be either: scalar (username) or an array    (c) $instids - reference to hash which will contain ID numbers. 
 #                if a single ID matches multiple usernames.                  keys will be unique IDs (student or faculty/staff ID)
 # returns 1 parameter - 'ok' if no processing error, or other value                   values will be either: scalar (username) or an array 
 #                       if an error occurred.                  if a single ID matches multiple usernames.
 # side effects - populates the $instusers and $instids refs to hashes.   returns 1 parameter - 'ok' if no processing error, or other value 
 #                with information for all users from all available                          if an error occurred.
 #                institutional datafeeds.   side effects - populates the $instusers and $instids refs to hashes.
 #                  with information for all users from all available 
 ###############################                  institutional datafeeds.
   
   
   =cut
   
 sub allusers_info {  sub allusers_info {
     my ($dom,$instusers,$instids) = @_;      my ($dom,$instusers,$instids) = @_;
Line 513  sub allusers_info { Line 566  sub allusers_info {
     return $outcome;       return $outcome; 
 }  }
   
 ###############################  =pod
 # sub get_userinfo  
 #  =item get_userinfo()
 # Incoming data: four required arguments and additional optional arguments  
 # Two modes of operation:   Incoming data: four required arguments and additional optional arguments
 # (1) Retrieves institutional data for a single user either by username   Two modes of operation:
 #     if $uname is included as second argument, or by ID if $id is    (1) Retrieves institutional data for a single user either by username
 #     included as a third argument.  Either (b) or (c) must be provided.       if $uname is included as second argument, or by ID if $id is 
 #     (g), (h) and (i) will be undefined.       included as a third argument.  Either (b) or (c) must be provided.
 # (2) Retrieves institutional user data from search of an institutional       (g), (h) and (i) will be undefined.
 #     directory based on a search. (g) and (h) are required.   (2) Retrieves institutional user data from search of an institutional
 #     (i) is optional. (b) and (c) will be undefined.        directory based on a search. (g) and (h) are required.
 #       (i) is optional. (b) and (c) will be undefined. 
 # (a) $dom - domain  
 # (b) $uname - username of user   (a) $dom - domain
 # (c) $id - student/faculty ID of user   (b) $uname - username of user
 # (d) $instusers - reference to hash which will contain info for user   (c) $id - student/faculty ID of user
 #                 as key = value; keys will be one or all of:   (d) $instusers - reference to hash which will contain info for user
 #                 lastname,firstname,middlename,generation,id,inststatus -                   as key = value; keys will be one or all of:
 #                 institutional status (e.g., faculty,staff,student)                   lastname,firstname,middlename,generation,id,inststatus -
 #                 Values are all scalars except inststatus,                   institutional status (e.g., faculty,staff,student)
 #                 which is an array.                   Values are all scalars except inststatus,
 # (e) $instids - reference to hash which will contain ID numbers -                    which is an array.
 #                 keys will be unique IDs (student or faculty/staff ID)     (e) $instids - reference to hash which will contain ID numbers - 
 #                 values will be either: scalar (username) or an array                   keys will be unique IDs (student or faculty/staff ID)  
 #                 if a single ID matches multiple usernames.                   values will be either: scalar (username) or an array
 # (f) $types - optional reference to array which contains                    if a single ID matches multiple usernames.
 #              institutional types to check.   (f) $types - optional reference to array which contains 
 # (g) $srchby - optional if $uname or $id defined, otherwise required.                institutional types to check.
 #               Allowed values include: 1. lastfirst, 2. last, 3. uname   (g) $srchby - optional if $uname or $id defined, otherwise required.
 #               corresponding to searches by 1. lastname,firstname;                 Allowed values include: 1. lastfirst, 2. last, 3. uname
 #               2. lastname; 3. username                 corresponding to searches by 1. lastname,firstname;
 # (h) $srchterm - optional if $uname or $id defined, otherwise required                 2. lastname; 3. username
 #                String to search for.   (h) $srchterm - optional if $uname or $id defined, otherwise required
 # (i) $srchtype - optional. Allowed values: contains, begins (defaults                  String to search for.
 #                to exact match otherwise).   (i) $srchtype - optional. Allowed values: contains, begins (defaults
 #                  to exact match otherwise).
 # returns 1 parameter - 'ok' if no processing error, or other value   
 #                       if an error occurred.   returns 1 parameter - 'ok' if no processing error, or other value 
 # side effects - populates the $instusers and $instids refs to hashes.                         if an error occurred.
 #                with information for specified username, or specified   side effects - populates the $instusers and $instids refs to hashes.
 #                id, if fifth argument provided, from all available, or                   with information for specified username, or specified
 #                specified (e.g., faculty only) institutional datafeeds,                  id, if fifth argument provided, from all available, or 
 #                if sixth argument provided.                  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    WARNING: You need to set $outcome to 'ok' once you have customized
 #          directory data source, otherwise institutional directory             this routine to communicate with an instititional 
 #          searches will always be reported as being unavailable            directory data source, otherwise institutional directory 
 #          in domain $dom.            searches will always be reported as being unavailable
 #            in domain $dom.
 ###############################  
   =cut
   
 sub get_userinfo {  sub get_userinfo {
     my ($dom,$uname,$id,$instusers,$instids,$types,      my ($dom,$uname,$id,$instusers,$instids,$types,
Line 573  sub get_userinfo { Line 627  sub get_userinfo {
     return $outcome;      return $outcome;
 }  }
   
 ###############################  =pod
 # sub inst_usertypes   
 #  =item inst_usertypes() 
 # Incoming data: three arguments  
 # (a) $dom - domain   Incoming data: three arguments
 # (b) $usertypes - reference to hash which will contain    (a) $dom - domain
 #                 key = value, where keys are institution    (b) $usertypes - reference to hash which will contain 
 #                 affiliation types (e.g., Faculty, Student etc.)                   key = value, where keys are institution 
 #                 and values are titles (e.g., Faculty/Academic Staff)                   affiliation types (e.g., Faculty, Student etc.)
 # (c) $order - reference to array which will contain the order in                   and values are titles (e.g., Faculty/Academic Staff)
 #              which institutional types should be shown   (c) $order - reference to array which will contain the order in
 #              when displaying data tables (e.g., default quotas                    which institutional types should be shown
 #              or updateable user fields (see domainprefs.pm)                 when displaying data tables (e.g., default quotas    
 # returns 1 parameter - 'ok' if no processing error, or other value                 or updateable user fields (see domainprefs.pm) 
 #                        if an error occurred.   returns 1 parameter - 'ok' if no processing error, or other value 
 #                          if an error occurred.
 ###############################  
   
   =cut
   
 sub inst_usertypes {  sub inst_usertypes {
     my ($dom,$usertypes,$order) = @_;      my ($dom,$usertypes,$order) = @_;
Line 599  sub inst_usertypes { Line 655  sub inst_usertypes {
     return $outcome;      return $outcome;
 }  }
   
 ###############################  =pod
 # sub username_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, noncredit)   
 #                  for each key, value is a hash  
 #                      desc => long name for rule    
 #                      rule => description of rule  
 #                      authtype => (krb5,krb4,int, or loc)  
 #                                 authentication type for rule   
 #                      authparm => authentication parameter for rule  
 #                      authparmfixed => 1 if authparm used when  
 #                          creating user for rule must be authparm    
 #                      authmsg => Message to display describing   
 #                                 authentication to use for this rule  
 #  
 # (c) $rulesorder - reference to array containing rule names   
 #                   in order to be displayed  
   
 #  =item username_rules()
 #  returns 'ok' if no processing error.  
 #   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, noncredit) 
                     for each key, value is a hash
                         desc => long name for rule  
                         rule => description of rule
                         authtype => (krb5,krb4,int, or loc)
                                    authentication type for rule 
                         authparm => authentication parameter for rule
                         authparmfixed => 1 if authparm used when
                             creating user for rule must be authparm  
                         authmsg => Message to display describing 
                                    authentication to use for this rule
   
    (c) $rulesorder - reference to array containing rule names 
                      in order to be displayed
   
   
     returns 'ok' if no processing error.
   
   =cut
   
 sub username_rules {  sub username_rules {
     my ($dom,$ruleshash,$rulesorder) = @_;      my ($dom,$ruleshash,$rulesorder) = @_;
Line 633  sub username_rules { Line 690  sub username_rules {
     return $outcome;      return $outcome;
 }  }
   
 ###############################  =pod
 # sub id_rules  
 #  =item id_rules()
 # Incoming data: three arguments  
 # (a) $dom - domain   Incoming data: three arguments
 # (b) $ruleshash - reference to hash containing rules   (a) $dom - domain
 #                  (a hash of a hash)   (b) $ruleshash - reference to hash containing rules
 #                  keys of top level hash are short names                    (a hash of a hash)
 #                   (e.g., netid, noncredit)                    keys of top level hash are short names
 #                  for each key, value is a hash                     (e.g., netid, noncredit)
 #                      desc => long name for rule                    for each key, value is a hash
 #                      rule => description of rule                        desc => long name for rule
 #                        rule => description of rule
 # (c) $rulesorder - reference to array containing rule names  
 #                   in order to be displayed   (c) $rulesorder - reference to array containing rule names
 #                     in order to be displayed
 #  returns 'ok' if no processing error.  
 #    returns 'ok' if no processing error.
 ###############################  
   =cut
   
 sub id_rules {  sub id_rules {
     my ($dom,$ruleshash,$rulesorder) = @_;      my ($dom,$ruleshash,$rulesorder) = @_;
Line 659  sub id_rules { Line 717  sub id_rules {
     return $outcome;      return $outcome;
 }  }
   
 ###############################  =pod
 # sub selfcreate_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  
 #                      desc => long name for rule  
 #                      rule => description of rule  
 #  
 # (c) $rulesorder - reference to array containing rule names  
 #                   in order to be displayed  
 #  
 #  returns 'ok' if no processing error.  
 #  
 ###############################  
   
   =item selfcreate_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
                         desc => long name for rule
                         rule => description of rule
   
    (c) $rulesorder - reference to array containing rule names
                      in order to be displayed
   
     returns 'ok' if no processing error.
   
   
   =cut
   
 sub selfcreate_rules {  sub selfcreate_rules {
     my ($dom,$ruleshash,$rulesorder) = @_;      my ($dom,$ruleshash,$rulesorder) = @_;
Line 686  sub selfcreate_rules { Line 745  sub selfcreate_rules {
     return $outcome;      return $outcome;
 }  }
   
 ###############################  =pod
 # sub username_check   
 #  =item username_check() 
 # Incoming data: four arguments  
 # (a) $dom - domain (scalar)    Incoming data: four arguments
 # (b) $uname - username to compare against rules (scalar)   (a) $dom - domain (scalar) 
 # (c) $to_check (reference to array of rule names to check)   (b) $uname - username to compare against rules (scalar)
 # (d) $resultshash (reference to hash of results)   (c) $to_check (reference to array of rule names to check)
 #                    hash of results for rule checked   (d) $resultshash (reference to hash of results)
 #                   - keys are rule names                      hash of results for rule checked
 #                   - values are: 1 or 0 (for matched or unmatched)                      - keys are rule names
 #                     - values are: 1 or 0 (for matched or unmatched) 
 # returns 'ok' if no processing error.  
 #   returns 'ok' if no processing error.
 ###############################  
   
   =cut
   
 sub username_check {  sub username_check {
     my ($dom,$uname,$to_check,$resultshash) = @_;      my ($dom,$uname,$to_check,$resultshash) = @_;
Line 708  sub username_check { Line 769  sub username_check {
     return $outcome;       return $outcome; 
 }  }
   
 ###############################  =pod
 # sub id_check  
 #  =item id_check()
 # Incoming data: four arguments  
 # (a) $dom - domain (scalar)   Incoming data: four arguments
 # (b) $id - ID to compare against rules (scalar)   (a) $dom - domain (scalar)
 # (c) $to_check (reference to array of rule names to check)   (b) $id - ID to compare against rules (scalar)
 # (d) $resultshash (reference to hash of results)   (c) $to_check (reference to array of rule names to check)
 #                    hash of results for rule checked   (d) $resultshash (reference to hash of results)
 #                   - keys are rule names                      hash of results for rule checked
 #                   - values are: 1 or 0 (for matched or unmatched)                     - keys are rule names
 #                     - values are: 1 or 0 (for matched or unmatched)
 # returns 'ok' if no processing error.  
 #   returns 'ok' if no processing error.
 ###############################  
   
   =cut
   
 sub id_check {  sub id_check {
     my ($dom,$id,$to_check,$resultshash) = @_;      my ($dom,$id,$to_check,$resultshash) = @_;
Line 730  sub id_check { Line 793  sub id_check {
     return $outcome;      return $outcome;
 }  }
   
 ###############################  =pod
 # sub selfcreate_check  
 #  =item selfcreate_check()
 # Incoming data: four arguments  
 # (a) $dom - domain (scalar)   Incoming data: four arguments
 # (b) $selfcreatename - e-mail proposed as username (compare against rules - scalar)   (a) $dom - domain (scalar)
 # (c) $to_check (reference to array of rule names to check)   (b) $selfcreatename - e-mail proposed as username (compare against rules - scalar)
 # (d) $resultshash (reference to hash of results)   (c) $to_check (reference to array of rule names to check)
 #                   hash of results for rule checked   (d) $resultshash (reference to hash of results)
 #                   - keys are rule names                     hash of results for rule checked
 #                   - values are: 1 or 0 (for matched or unmatched)                     - keys are rule names
 #                     - values are: 1 or 0 (for matched or unmatched)
 # returns 'ok' if no processing error.  
 #   returns 'ok' if no processing error.
 ###############################  
   
   =cut
   
 sub selfcreate_check {  sub selfcreate_check {
     my ($dom,$selfcreatename,$to_check,$resultshash) = @_;      my ($dom,$selfcreatename,$to_check,$resultshash) = @_;
Line 752  sub selfcreate_check { Line 817  sub selfcreate_check {
     return $outcome;      return $outcome;
 }  }
   
 ###############################  =pod
 # sub AUTOLOAD  
 #  =item AUTOLOAD()
 # Incoming data: none  
 # Returns ''   Incoming data: none
 #   Returns ''
 # Prevents errors when undefined subroutines are called in this package  
 # Will allow new routines added in the future to be called from lond etc.   Prevents errors when undefined subroutines are called in this package
 # without the need for customized versions of local*.pm packages to be   Will allow new routines added in the future to be called from lond etc.
 # modified to include the new subroutines immediately.   without the need for customized versions of local*.pm packages to be
 #   modified to include the new subroutines immediately.
 # See "Programming Perl" 3rd ed. pp 296-298.     
 ###############################   See "Programming Perl" 3rd ed. pp 296-298.   
   
   =back
   
   =cut
   
 sub AUTOLOAD {  sub AUTOLOAD {
     our $AUTOLOAD;      our $AUTOLOAD;
Removed from v.1.31  
changed lines
  Added in v.1.32

FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>