Return to localenroll.pm CVS log

Up to [LON-CAPA] / loncom / enrollment

Created stub subroutines.  Included documentation to explain how each should
work.  Added an additional create_password subroutine that is called by
Enrollment.pm when a new user is to be added to the domain, and the
authentication method is set to "local". Not required at MSU.

    1: package localenroll;
    2: 
    3: use strict;
    4: 
    5: ################################
    6: # sub fetch_enrollment
    7: #
    8: # connects to the institutional classlist data source,
    9: # reads classlist data and stores in an XML file
   10: # in /home/httpd/perl/tmp/
   11: #
   12: # classlist files are named as follows:
   13: #
   14: # DOMAIN_COURSE_INSTITUTIONALCODE_classlist.xml
   15: #
   16: # e.g., msu_43551dedcd43febmsul1_fs03nop590001_classlist.xml
   17: # where DOMAIN = msu  COURSE = 43551dedcd43febmsul1 
   18: # INSTITUTIONALCODE = fs03nop590001 
   19: # (MSU's course naming scheme - fs03 = Fall semester 2003, nop =
   20: # department name, 590 = course number, 001 = section number.
   21: #
   22: # fetch_enrollment requires three arguments -
   23: # $dom - DOMAIN e.g., msu
   24: # $affiliatesref - a reference to a hash of arrays that contains LON-CAPA 
   25: # courses that are to be updated as keys, and institutional coursecodes 
   26: # contributing enrollment to that LON-CAPA course as elements in each array.
   27: # $replyref - a reference to a hash that contains LON-CAPA courses
   28: # that are to be updated as keys, and the total enrollment count in all 
   29: # affiliated sections, as determined from institutional data as hash elements. 
   30: #
   31: # As an example, if fetch_enrollment is called to retrieve institutional
   32: # classlists for a single LON-CAPA course - 43551dedcd43febmsul1 which 
   33: # corresponds to fs03nop590, sections 001, 601 and 602 , and the course
   34: # also accommodates enrollment from a crosslisted course in the ost
   35: # department - fs03ost580002:
   36: #
   37: # the affiliatesref would be a reference to %affiliates which would be:
   38: #
   39: # @{$affiliates{'43551dedcd43febmsul1'}} =
   40: #   ("fs03nop590001","fs03nop590601","fs03nop590602","fs03ost580002");
   41: #
   42: # fetch_enrollment would create four files in /home/httpd/perl/tmp/.
   43: # msu_43551dedcd43febmsul1_fs03nop590001_classlist.xml
   44: # msu_43551dedcd43febmsul1_fs03nop590601_classlist.xml
   45: # msu_43551dedcd43febmsul1_fs03nop590602_classlist.xml
   46: # msu_43551dedcd43febmsul1_fs03ost580002_classlist.xml
   47: #
   48: # In each file, student data would be stored in the following format
   49: # 
   50: # <student username="smith">
   51: #  <autharg>MSU.EDU</autharg>
   52: #  <authtype>krb4</authtype>
   53: #  <email>smith@msu.edu</email>
   54: #  <enddate></enddate>
   55: #  <firstname>John</firstname>
   56: #  <generation>II</generation>
   57: #  <groupID>fs03nop590001</groupID>
   58: #  <lastname>Smith</lastname>
   59: #  <middlename>D</middlename>
   60: #  <startdate></startdate>
   61: #  <studentID>A12345678</studentID>
   62: # </student>
   63: # 
   64: # with the following at the top of the file
   65: #<?xml version="1.0" encoding="UTF-8"?>
   66: #<!DOCTYPE text>
   67: #<students>
   68: #
   69: # (all comment - #s removed)
   70: #
   71: # and a closing:
   72: #</students>
   73: #
   74: # The <startdate> and the <enddate> are the activation date and expiration date
   75: # for this student's role. If they are absent, then the date set for
   76: # first automated enrollment is used as the default activation date, and the
   77: # date set for last automated enrollment is used as the default expiration date.
   78: # If dates are to included in the XML file, they should be in the format
   79: # YYYY:MM:DD:HH:MM:SS (: separators required).
   80: #
   81: # If there were 10 students in fs03nop590001, 5 students in fs03nop59o601, 
   82: # 8 students in fs03nop590602, and 2 students in fs03ost580002,
   83: # then $$reply{'43551dedcd43febmsul1'} = 25
   84: #
   85: # The purpose of the %reply hash is to detect cases where the institutional 
   86: # enrollment is 0 (most likely due to a problem with the data source).
   87: # In such a case, the LON-CAPA course roster is left unchanged (i.e., no
   88: # students are expired, even if automated drops is enabled.
   89: # 
   90: # fetch_enrollment should return a 0 or 1, depending on whether a connection
   91: # could be established to the institutional data source.
   92: # 0 is returned if no connection could be made.
   93: # 1 is returned if connection was successful
   94: #
   95: # A return of 1 is required for the calling modules to perform LON-CAPA
   96: # roster changes based on the contents of the XML classlist file(s), e,g,,
   97: # msu_43551dedcd43febmsul1_fs03nop590001_classlist.xml
   98: #
   99: # XML classlist files are temporary. They are deleted after the enrollment 
  100: # update process in the calling module is complete.
  101: #
  102: ################################
  103: 
  104: sub fetch_enrollment {
  105:   my ($dom,$affiliatesref,$replyref) = @_;
  106:      foreach my $crs (sort keys %{$affiliatesref}) {
  107:          $$replyref{$crs} = 0;
  108:      }
  109:   }
  110:   my $okflag = 0;
  111:   return $okflag;
  112: }
  113: 
  114: ###############################
  115: # sub get_sections
  116: #
  117: # This is called by the Automated Enrollment Manager interface
  118: # (lonpopulate.pm) to create an array of valid sections for 
  119: # a specific institutional coursecode.
  120: # e.g., for MSU coursecode: fs03nop590
  121: # ("001","601","602") would be returned
  122: #
  123: # If the array returned contains at least one element, then 
  124: # the interface offerred to the course coordinator, lists
  125: # official sections and provides a checkbox to use to
  126: # select enrollment in the LON-CAPA course from each official section.  
  127: #
  128: # get_sections requires one argument - the instituional coursecode
  129: # (in the MSU case this is a concatenation of semester code, department
  130: # and course number). 
  131: # 
  132: # If there is no access to official course sections at your institution,
  133: # then an empty array is returned, and the Automated Enrollment Manager
  134: # interface will allow the course coordinator to enter section numbers
  135: # in text boxes.
  136: # 
  137: ################################ 
  138: 
  139: sub get_sections {
  140:     my $coursecode = shift;
  141:     my @secs = ();
  142:     return @secs;
  143: }
  144: 
  145: ###############################
  146: # sub new_course
  147: #
  148: # This is called by loncreatecourse.pm and 
  149: # lonpopulate.pm to record that fact that a new course section
  150: # has been added to LON-CAPA that requires access to institutional data
  151: # At MSU, this is required, as institutional classlists can only made
  152: # available to faculty who are officially assigned to a course
  153: # 
  154: # The new_course subroutine is used to check that the course owner
  155: # of the LON-CAPA course is permitted to access the institutional
  156: # classlist for any course sections and crosslisted classes that
  157: # the course coordinator wishes to have affiliated with the course.
  158: # 
  159: # If access is permitted, then 'ok' is returned.
  160: # The course section or crosslisted course will only be added to the list of
  161: # affiliates if 'ok' is returned.
  162: #
  163: # new_course requires two arguments -
  164: # the institutional courseID (in the MSU case this is a concatenation of 
  165: # semester code, department code, course number, and section number
  166: # e.g., fs03nop590001).
  167: # the course owner. This is the LON-CAPA username of the course coordinator 
  168: # assigned to the course when it is first created.
  169: #
  170: #################################
  171: 
  172: sub new_course  {
  173:     my ($course_id,$owner) = @_;
  174:     my $outcome = 'ok';
  175:     return $outcome;
  176: }
  177: 
  178: ###############################
  179: # sub validate_courseID
  180: #
  181: # This is called whenever a new course section or crosslisted course
  182: # is being affiliated with a LON-CAPA course (i.e., by loncreatecourse.pm
  183: # and the Automated Enrollment Manager in lonpopulate.pm).
  184: # A check is made that the courseID that the course coordinator wishes
  185: # to affiliate with the course is valid according to the institutional
  186: # schedule of official classes 
  187: #
  188: # A valid courseID is confirmed by returning 'ok'
  189: #
  190: # validate_courseID requires one argument -
  191: # the institutional courseID (in the MSU case this is a concatenation of
  192: # semester code, department code, course number, and section number
  193: # e.g., fs03nop590001).
  194: #
  195: ###############################  
  196: 
  197: sub validate_courseID {
  198:     my $course_id = shift;
  199:     my $outcome = 'ok';
  200:     return $outcome;   
  201: }
  202: 
  203: ###############################
  204: # sub create_password 
  205: #
  206: # This is called when the authentication method set for the automated 
  207: # enrollment process when enrolling new users in the domain is "local".
  208: # This could be signalled for the specific user by the value of local
  209: # for the <authtype> tag from the classlist.xml files, or if this is blank,
  210: # the default authtype, set by the domain coordinator when creating the course
  211: # with loncreatecourse.pm.
  212: # 
  213: # create_password requires one argument -
  214: # the value of <autharg> from the classlist.xml files, or if this is blank,
  215: # the default autharg, set by the domain coordinator when creating the course
  216: # with loncreatecourse.pm.  
  217: #
  218: # Three values are returned:
  219: # (a) the value of $authparam - which might have been changed
  220: # (b) a flag to indicate whether a password had been created
  221: # 0 means no password created
  222: # 1 means password created.  In this case the calling module - Enrollment.pm
  223: # will send the LON-CAPA username and passwod to the new user's e-mail
  224: # (if one was provided), or to the course owner (if one was not provided and
  225: # the new user was created by the automated process), or to the active
  226: # course coordinator (if the new user was created using the 'update roster
  227: # now' interface included in the Automated Enrollment Manager.  
  228: # (c) a flag to indicate that the authentication method is correct - 'ok'.
  229: # If $authchk is not set to 'ok' then account creation and enrollment of the 
  230: # new user will not occur.
  231: #    
  232: ###############################
  233: 
  234: sub create_password {
  235:     my $authparam = shift;
  236:     my $authchk = 'ok';
  237:     my $create_passwd = 0;
  238:     return ($authparam,$create_passwd,$authchk);
  239: }
  240: 
  241: 1;