--- loncom/enrollment/localenroll.pm 2003/12/09 20:06:37 1.3 +++ loncom/enrollment/localenroll.pm 2003/12/11 00:39:54 1.4 @@ -1,117 +1,241 @@ -# local bits for automated enrollment -# $Id: localenroll.pm,v 1.3 2003/12/09 20:06:37 albertel Exp $ -# -# Copyright Michigan State University Board of Trustees -# -# This file is part of the LearningOnline Network with CAPA (LON-CAPA). -# -# LON-CAPA is free software; you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation; either version 2 of the License, or -# (at your option) any later version. -# -# LON-CAPA is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with LON-CAPA; if not, write to the Free Software -# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA -# -# /home/httpd/html/adm/gpl.txt -# -# http://www.lon-capa.org/ -# package localenroll; use strict; -use DBI; -use LONCAPA::Configuration; + +################################ +# sub fetch_enrollment +# +# connects to the institutional classlist data source, +# reads classlist data and stores in an XML file +# in /home/httpd/perl/tmp/ +# +# classlist files are named as follows: +# +# DOMAIN_COURSE_INSTITUTIONALCODE_classlist.xml +# +# e.g., msu_43551dedcd43febmsul1_fs03nop590001_classlist.xml +# where DOMAIN = msu COURSE = 43551dedcd43febmsul1 +# INSTITUTIONALCODE = fs03nop590001 +# (MSU's course naming scheme - fs03 = Fall semester 2003, nop = +# department name, 590 = course number, 001 = section number. +# +# fetch_enrollment requires three arguments - +# $dom - DOMAIN e.g., msu +# $affiliatesref - a reference to a hash of arrays that contains LON-CAPA +# courses that are to be updated as keys, and institutional coursecodes +# contributing enrollment to that LON-CAPA course as elements in each array. +# $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 +# affiliated sections, as determined from institutional data as hash elements. +# +# As an example, if fetch_enrollment is called to retrieve institutional +# classlists for a single LON-CAPA course - 43551dedcd43febmsul1 which +# corresponds to fs03nop590, sections 001, 601 and 602 , and the course +# also accommodates enrollment from a crosslisted course in the ost +# department - fs03ost580002: +# +# the affiliatesref would be a reference to %affiliates which would be: +# +# @{$affiliates{'43551dedcd43febmsul1'}} = +# ("fs03nop590001","fs03nop590601","fs03nop590602","fs03ost580002"); +# +# fetch_enrollment would create four files in /home/httpd/perl/tmp/. +# msu_43551dedcd43febmsul1_fs03nop590001_classlist.xml +# msu_43551dedcd43febmsul1_fs03nop590601_classlist.xml +# msu_43551dedcd43febmsul1_fs03nop590602_classlist.xml +# msu_43551dedcd43febmsul1_fs03ost580002_classlist.xml +# +# In each file, student data would be stored in the following format +# +# +# MSU.EDU +# krb4 +# smith@msu.edu +# +# John +# II +# fs03nop590001 +# Smith +# D +# +# A12345678 +# +# +# with the following at the top of the file +# +# +# +# +# (all comment - #s removed) +# +# and a closing: +# +# +# The and the are the activation date and expiration date +# for this student's role. If they are absent, then the date set for +# first automated enrollment is used as the default activation date, and the +# date set for last automated enrollment is used as the default expiration date. +# If dates are to included in the XML file, they should be in the format +# YYYY:MM:DD:HH:MM:SS (: separators required). +# +# If there were 10 students in fs03nop590001, 5 students in fs03nop59o601, +# 8 students in fs03nop590602, and 2 students in fs03ost580002, +# then $$reply{'43551dedcd43febmsul1'} = 25 +# +# The purpose of the %reply hash is to detect cases where the institutional +# 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 +# students are expired, even if automated drops is enabled. +# +# fetch_enrollment should return a 0 or 1, depending on whether a connection +# could be established to the institutional data source. +# 0 is returned if no connection could be made. +# 1 is returned if connection was successful +# +# 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,, +# msu_43551dedcd43febmsul1_fs03nop590001_classlist.xml +# +# XML classlist files are temporary. They are deleted after the enrollment +# update process in the calling module is complete. +# +################################ sub fetch_enrollment { my ($dom,$affiliatesref,$replyref) = @_; - $ENV{SYBASE} = '/usr/local/freetds'; - - my $DB_PATH = "dbi:Sybase:server=ESDB1;database=RO_ClassList"; - my $DB_USER =""; # Not stored in CVS - my $DB_PASSWD = ""; # Not stored in CVS - - my $configvars = &LONCAPA::Configuration::read_conf('loncapa.conf'); - - my $dbh= DBI->connect($DB_PATH,$DB_USER,$DB_PASSWD); - my $dbflag = 0; - if (defined $dbh) { - $dbflag = 1; foreach my $crs (sort keys %{$affiliatesref}) { - my $xmlstem = $$configvars{'lonDaemons'}."/tmp/".$dom."_".$crs."_"; - $$replyref{$crs} = &write_class_data ($dbh,$xmlstem,\@{$$affiliatesref{$crs}}); + $$replyref{$crs} = 0; } - $dbh->disconnect; } - return $dbflag; + my $okflag = 0; + return $okflag; } -sub write_class_data { - my ($dbh,$xmlstem,$coursesref) = @_; - my $stucount = 0; - foreach my $class (@{$coursesref}) { - if ($class =~ m/^([suf]s\d{2})(\w{2,3})(\d{3,4}\w?)(\d{3})$/) { - my $xmlfile = $xmlstem.$class."_classlist.xml"; - open(FILE, ">$xmlfile"); - print FILE qq| - - -|; - - my $sth = $dbh->prepare("SELECT Pid,Pilot_Id,Student_Name FROM LONCAPA_ClassList WHERE Term_Code = '$1' AND Subj_Code = '$2' AND Crse_Code = '$3' AND Sctn_Code = '$4' ORDER BY Student_Name"); - $sth->execute(); - while ( my($pid,$pilot,$name) = $sth->fetchrow_array ) { - $stucount ++; - $name =~ s/^\s//g; - $name =~ s/\s$//g; - my ($last,$given,$first,$middle); - $last = substr($name,0,index($name,",")); - $given = substr($name,index($name,",")+1); - $given =~ s/^\s//g; - if ($given =~ m/\w\s\w/) { - $first = substr($given,0,index($given," ")); - $middle = substr($given,index($given," ")+1); - $middle =~ s/\s//g; - } else { - $first = $given; - } - $first =~ s/\s$//g; - print FILE qq| - MSU.EDU - krb4 - $pilot\@msu.edu - - $first - - $class - $last - $middle - - $pid - -|; -# Format for startdate is YYYY:MM:DD:HH:MM:SS -# Format forenddate is YYYY:MM:DD:HH:MM:SS -# Authentication is one of: krb4, krb5, int or loc -# Password is either the password for int, or Kerberos domain (for krb4 or krb5), or argument (for loc). -# If authentication, password, startdate or enddate are blank, the default for the course is used. These defaults can be modified using the Automated Enrollment Manager. - } - $sth->finish; - print FILE qq||; - close(FILE); - } - } - return $stucount; -} +############################### +# sub get_sections +# +# This is called by the Automated Enrollment Manager interface +# (lonpopulate.pm) to create an array of valid sections for +# a specific institutional coursecode. +# 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 +# official sections and provides a checkbox to use to +# select enrollment in the LON-CAPA course from each official section. +# +# get_sections requires one argument - the instituional coursecode +# (in the MSU case this is a concatenation of semester code, department +# and course number). +# +# If there is no access to official course sections at your institution, +# then an empty array is returned, and the Automated Enrollment Manager +# interface will allow the course coordinator to enter section numbers +# in text boxes. +# +################################ sub get_sections { + my $coursecode = shift; + my @secs = (); + return @secs; +} + +############################### +# sub new_course +# +# This is called by loncreatecourse.pm and +# lonpopulate.pm to record that fact that a new course section +# has been added to LON-CAPA that requires access to institutional data +# 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 +# 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 +# affiliates if 'ok' is returned. +# +# new_course requires two arguments - +# the institutional courseID (in the MSU case this is a concatenation of +# semester code, department code, course number, and section number +# e.g., fs03nop590001). +# the course owner. This is the LON-CAPA username of the course coordinator +# assigned to the course when it is first created. +# +################################# + +sub new_course { + my ($course_id,$owner) = @_; + my $outcome = 'ok'; + return $outcome; +} + +############################### +# sub 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 +# and the Automated Enrollment Manager in lonpopulate.pm). +# A check is made that the courseID that the course coordinator wishes +# to affiliate with the course is valid according to the institutional +# schedule of official classes +# +# A valid courseID is confirmed by returning 'ok' +# +# validate_courseID requires one argument - +# the institutional courseID (in the MSU case this is a concatenation of +# semester code, department code, course number, and section number +# e.g., fs03nop590001). +# +############################### + +sub validate_courseID { + my $course_id = shift; + my $outcome = 'ok'; + return $outcome; +} +############################### +# sub create_password +# +# This is called when the authentication method set for the automated +# enrollment process when enrolling new users in the domain is "local". +# This could be signalled for the specific user by the value of local +# for the tag from the classlist.xml files, or if this is blank, +# the default authtype, set by the domain coordinator when creating the course +# with loncreatecourse.pm. +# +# create_password requires one argument - +# the value of from the classlist.xml files, or if this is blank, +# the default autharg, set by the domain coordinator when creating the course +# with loncreatecourse.pm. +# +# Three values are returned: +# (a) the value of $authparam - which might have been changed +# (b) a flag to indicate whether a password had been created +# 0 means no password created +# 1 means password created. In this case the calling module - Enrollment.pm +# will send the LON-CAPA username and passwod to the new user's e-mail +# (if one was provided), or to the course owner (if one was not provided and +# the new user was created by the automated process), or to the active +# course coordinator (if the new user was created using the 'update roster +# now' interface included in the Automated Enrollment Manager. +# (c) a flag to indicate that the authentication method is correct - 'ok'. +# If $authchk is not set to 'ok' then account creation and enrollment of the +# new user will not occur. +# +############################### + +sub create_password { + my $authparam = shift; + my $authchk = 'ok'; + my $create_passwd = 0; + return ($authparam,$create_passwd,$authchk); } 1;