Annotation of loncom/enrollment/localenroll.pm, revision 1.34

1.5       albertel    1: # functions to glue school database system into Lon-CAPA for 
                      2: # automated enrollment
1.34    ! weissno     3: # $Id: localenroll.pm,v 1.34 2009/03/08 02:06:20 weissno Exp $
1.5       albertel    4: #
                      5: # Copyright Michigan State University Board of Trustees
                      6: #
                      7: # This file is part of the LearningOnline Network with CAPA (LON-CAPA).
                      8: #
                      9: # LON-CAPA is free software; you can redistribute it and/or modify
                     10: # it under the terms of the GNU General Public License as published by
                     11: # the Free Software Foundation; either version 2 of the License, or
                     12: # (at your option) any later version.
                     13: #
                     14: # LON-CAPA is distributed in the hope that it will be useful,
                     15: # but WITHOUT ANY WARRANTY; without even the implied warranty of
                     16: # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
                     17: # GNU General Public License for more details.
                     18: #
                     19: # You should have received a copy of the GNU General Public License
                     20: # along with LON-CAPA; if not, write to the Free Software
                     21: # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
                     22: #
                     23: # /home/httpd/html/adm/gpl.txt
                     24: #
                     25: # http://www.lon-capa.org/
                     26: #
1.32      jms        27: 
                     28: =pod
                     29: 
                     30: =head1 NAME
                     31: 
                     32: localenroll
                     33: 
                     34: =head1 SYNOPSIS
                     35: 
                     36: This is part of the LearningOnline Network with CAPA project
                     37: described at http://www.lon-capa.org.
                     38: 
                     39: 
                     40: =head1 NOTABLE SUBROUTINES
                     41: 
                     42: =over
                     43: 
                     44: =back
                     45: 
                     46: =cut
                     47: 
1.4       raeburn    48: package localenroll;
                     49: 
                     50: use strict;
1.6       albertel   51: 
1.32      jms        52: =pod
                     53:  
                     54: =item run()
                     55:  set this to return 1 if you want the auto enrollment to run
                     56: 
                     57:  Beginning with LON-CAPA version 2.4, use of this routine is
                     58:  deprecated.  Whether or not Autoenroll.pl should run is set
                     59:  by the Domain Coordinator via "Set domain configuration",
                     60:  provided in the Domain Management section of the Main menu. 
                     61: 
                     62: =cut
1.6       albertel   63: 
1.9       raeburn    64: sub run() {
                     65:     my $dom = shift;
                     66:     return 0;
                     67: }
1.4       raeburn    68: 
1.32      jms        69: 
                     70: =pod
                     71: 
                     72: =item fetch_enrollment()
                     73: 
                     74:  connects to the institutional classlist data source,
                     75:  reads classlist data and stores in an XML file
                     76:  in /home/httpd/perl/tmp/
                     77: 
                     78:  classlist files are named as follows:
                     79: 
                     80:  DOMAIN_COURSE_INSTITUTIONALCODE_classlist.xml
                     81: 
                     82:  e.g., msu_43551dedcd43febmsul1_fs03nop590001_classlist.xml
                     83:  where DOMAIN = msu  COURSE = 43551dedcd43febmsul1 
                     84:  INSTITUTIONALCODE = fs03nop590001 
                     85:  (MSU's course naming scheme - fs03 = Fall semester 2003, nop =
                     86:  department name, 590 = course number, 001 = section number.)
                     87: 
                     88:  fetch_enrollment requires three arguments -
                     89:  $dom - DOMAIN e.g., msu
                     90:  $affiliatesref - a reference to a hash of arrays that contains LON-CAPA 
                     91:  courses that are to be updated as keys, and institutional coursecodes 
                     92:  contributing enrollment to that LON-CAPA course as elements in each array.
                     93:  $replyref - a reference to a hash that contains LON-CAPA courses
                     94:  that are to be updated as keys, and the total enrollment count in all 
                     95:  affiliated sections, as determined from institutional data as hash elements. 
                     96: 
                     97:  As an example, if fetch_enrollment is called to retrieve institutional
                     98:  classlists for a single LON-CAPA course - 43551dedcd43febmsul1 which 
                     99:  corresponds to fs03nop590, sections 001, 601 and 602 , and the course
                    100:  also accommodates enrollment from a crosslisted course in the ost
                    101:  department - fs03ost580002:
                    102: 
                    103:  the affiliatesref would be a reference to %affiliates which would be:
                    104: 
                    105:  @{$affiliates{'43551dedcd43febmsul1'}} =
                    106:    ("fs03nop590001","fs03nop590601","fs03nop590602","fs03ost580002");
                    107: 
                    108:  fetch_enrollment would create four files in /home/httpd/perl/tmp/.
                    109:  msu_43551dedcd43febmsul1_fs03nop590001_classlist.xml
                    110:  msu_43551dedcd43febmsul1_fs03nop590601_classlist.xml
                    111:  msu_43551dedcd43febmsul1_fs03nop590602_classlist.xml
                    112:  msu_43551dedcd43febmsul1_fs03ost580002_classlist.xml
                    113: 
                    114:  In each file, student data would be stored in the following format
                    115:  
                    116:  <student username="smith">
                    117:   <autharg>MSU.EDU</autharg>
                    118:   <authtype>krb4</authtype>
                    119:   <email>smith@msu.edu</email>
                    120:   <enddate></enddate>
                    121:   <firstname>John</firstname>
                    122:   <generation>II</generation>
                    123:   <groupID>fs03nop590001</groupID>
                    124:   <lastname>Smith</lastname>
                    125:   <middlename>D</middlename>
                    126:   <startdate></startdate>
                    127:   <studentID>A12345678</studentID>
                    128:  </student>
                    129:  
                    130:  with the following at the top of the file
                    131: <?xml version="1.0" encoding="UTF-8"?>
                    132: <!DOCTYPE text>
                    133: <students>
                    134: 
                    135:  (all comment - s removed)
                    136: 
                    137:  and a closing:
                    138: </students>
                    139: 
                    140:  The <startdate> and the <enddate> are the activation date and expiration date
                    141:  for this student's role. If they are absent, then the default access start and
                    142:  default access end dates are used. The default access dates can be set when 
                    143:  the course is created, and can be modified using the Automated Enrollment
                    144:  Manager, or via the 'Upload a class list','Enroll a single student' or 
                    145:  'Modify student data' utilities in the Enrollment Manager, by checking the 
                    146:  'make these dates the default for future enrollment' checkbox. If no default 
                    147:  dates have been set, then the tudent role will be active immediately, and will 
                    148:  remain active until the role is explicitly expired using ENRL -> Drop students. 
                    149:  If dates are to included in the XML file, they should be in the format
                    150:  YYYY:MM:DD:HH:MM:SS (: separators required).
                    151: 
                    152:  If there were 10 students in fs03nop590001, 5 students in fs03nop59o601, 
                    153:  8 students in fs03nop590602, and 2 students in fs03ost580002,
                    154:  then $$reply{'43551dedcd43febmsul1'} = 25
                    155: 
                    156:  The purpose of the %reply hash is to detect cases where the institutional 
                    157:  enrollment is 0 (most likely due to a problem with the data source).
                    158:  In such a case, the LON-CAPA course roster is left unchanged (i.e., no
                    159:  students are expired, even if automated drops is enabled.
                    160:  
                    161:  fetch_enrollment should return a 0 or 1, depending on whether a connection
                    162:  could be established to the institutional data source.
                    163:  0 is returned if no connection could be made.
                    164:  1 is returned if connection was successful
                    165: 
                    166:  A return of 1 is required for the calling modules to perform LON-CAPA
                    167:  roster changes based on the contents of the XML classlist file(s), e,g,,
                    168:  msu_43551dedcd43febmsul1_fs03nop590001_classlist.xml
                    169: 
                    170:  XML classlist files are temporary. They are deleted after the enrollment 
                    171:  update process in the calling module is complete.
                    172: 
                    173: 
                    174: =cut
1.1       raeburn   175: 
                    176: sub fetch_enrollment {
1.7       matthew   177:     my ($dom,$affiliatesref,$replyref) = @_;
                    178:     foreach my $crs (sort keys %{$affiliatesref}) {
                    179:         $$replyref{$crs} = 0;
                    180:     }
                    181:     my $okflag = 0;
                    182:     return $okflag;
1.4       raeburn   183: }
                    184: 
1.32      jms       185: =pod
                    186: 
                    187: =item get_sections()
                    188: 
                    189:  This is called by the Automated Enrollment Manager interface
                    190:  (lonpopulate.pm) to create an array of valid sections for 
                    191:  a specific institutional coursecode.
                    192:  e.g., for MSU coursecode: fs03nop590
                    193:  ("001","601","602") would be returned
                    194: 
                    195:  If the array returned contains at least one element, then 
                    196:  the interface offerred to the course coordinator, lists
                    197:  official sections and provides a checkbox to use to
                    198:  select enrollment in the LON-CAPA course from each official section.  
                    199: 
                    200:  get_sections takes two arguments - (a) the institutional coursecode
                    201:  (in the MSU case this is a concatenation of semester code, department
                    202:  and course number), and (b) the LON-CAPA domain that contains the course. 
                    203:  
                    204:  If there is no access to official course sections at your institution,
                    205:  then an empty array is returned, and the Automated Enrollment Manager
                    206:  interface will allow the course coordinator to enter section numbers
                    207:  in text boxes.
                    208:  
                    209: 
                    210: 
                    211: =cut
1.4       raeburn   212: 
                    213: sub get_sections {
1.9       raeburn   214:     my ($coursecode,$dom) = @_;
1.4       raeburn   215:     my @secs = ();
                    216:     return @secs;
1.1       raeburn   217: }
                    218: 
1.32      jms       219: =pod
                    220: 
                    221: =item new_course()
                    222: 
                    223:  This is called by loncreatecourse.pm and 
                    224:  lonpopulate.pm to record that fact that a new course section
                    225:  has been added to LON-CAPA that requires access to institutional data
                    226:  At MSU, this is required, as institutional classlists can only made
                    227:  available to faculty who are officially assigned to a course.
                    228:  
                    229:  The new_course subroutine is used to check that the course owner
                    230:  of the LON-CAPA course is permitted to access the institutional
                    231:  classlist for any course sections and crosslisted classes that
                    232:  the course coordinator wishes to have affiliated with the course.
                    233:  
                    234:  If access is permitted, then 'ok' is returned.
                    235:  The course section or crosslisted course will only be added to the list of
                    236:  affiliates if 'ok' is returned.
                    237: 
                    238:  new_course takes three arguments -
                    239:  (a) the institutional courseID (in the MSU case this is a concatenation of 
                    240:  semester code, department code, course number, and section number
                    241:  e.g., fs03nop590001).
                    242:  (b) the course owner. This is the LON-CAPA username and domain of the course 
                    243:  coordinator assigned to the course when it is first created, in the form
                    244:  username:domain
                    245:  (c) the LON-CAPA domain that contains the course
                    246: 
                    247: =cut
1.4       raeburn   248: 
                    249: sub new_course  {
1.9       raeburn   250:     my ($course_id,$owner,$dom) = @_;
1.4       raeburn   251:     my $outcome = 'ok';
                    252:     return $outcome;
1.1       raeburn   253: }
                    254: 
1.32      jms       255: =pod
                    256: 
                    257: =item validate_courseID()
                    258: 
                    259:  This is called whenever a new course section or crosslisted course
                    260:  is being affiliated with a LON-CAPA course (i.e., by loncreatecourse.pm
                    261:  and the Automated Enrollment Manager in lonpopulate.pm).
                    262:  A check is made that the courseID that the course coordinator wishes
                    263:  to affiliate with the course is valid according to the institutional
                    264:  schedule of official classes 
                    265: 
                    266:  A valid courseID is confirmed by returning 'ok'
                    267: 
                    268:  validate_courseID takes two arguments -
                    269:  (a) the institutional courseID (in the MSU case this is a concatenation of
                    270:  semester code, department code, course number, and section number
                    271:  e.g., fs03nop590001).
                    272:  (b) the LON-CAPA domain that contains the course
                    273: 
                    274: =cut  
1.4       raeburn   275: 
                    276: sub validate_courseID {
1.9       raeburn   277:     my ($course_id,$dom) = @_;
1.4       raeburn   278:     my $outcome = 'ok';
                    279:     return $outcome;   
                    280: }
1.1       raeburn   281: 
1.32      jms       282: =pod
                    283: 
                    284: =item create_password()
                    285: 
                    286:  This is called when the authentication method set for the automated 
                    287:  enrollment process when enrolling new users in the domain is "localauth".
                    288:  This could be signalled for the specific user by the value of localauth
                    289:  for the <authtype> tag from the classlist.xml files, or if this is blank,
                    290:  the default authtype, set by the domain coordinator when creating the course
                    291:  with loncreatecourse.pm.
                    292:   
                    293:  create_password takes three arguments -
                    294:  (a) $authparam - the value of <autharg> from the classlist.xml files,
                    295:  or if this blank, the default autharg, set by the domain coordinator when 
                    296:  creating the course with loncreatecourse.pm
                    297:  (b) $dom - the domain of the new user.
                    298:  (c) $username - the username of the new user (currently not actually used)
                    299: 
                    300:  Four values are returned:
                    301:  (a) the value of $authparam - which might have been changed
                    302:  (b) a flag to indicate whether a password had been created
                    303:  0 means no password created
                    304:  1 means password created.  In this case the calling module - Enrollment.pm
                    305:  will send the LON-CAPA username and password to the new user's e-mail
                    306:  (if one was provided), or to the course owner (if one was not provided and
                    307:  the new user was created by the automated process), or to the active
                    308:  course coordinator (if the new user was created using the 'update roster
                    309:  now' interface included in the Automated Enrollment Manager).  
                    310:  (c) a flag to indicate that the authentication method is correct - 'ok'.
                    311:  If $authchk is not set to 'ok' then account creation and enrollment of the 
                    312:  new user will not occur.
                    313:  (d) if a password was created it can be sent along.  This is the password 
                    314:  which will be included in the e-mail sent to the new user, or made available    
                    315:  to the course owner/course coordinator if no e-mail address is provided. If
                    316:  you do not wish to send a password, but want to give instructions on obtaining
                    317:  one, you could set $newpasswd as those instructions. (e.g.,
                    318:  $newpasswd = '(Please visit room 212, ACNS Bldg. to obtain your password)';
                    319:  The value of $newpasswd is NOT written in the user's LON-CAPA passwd file in
                    320:  /home/httpd/lonUsers/$dom/a/b/c/abcuser/passwd, which in the case of a user
                    321:  employing localauth will contain 'localauth:$authparam'.  If you need to include
                    322:  a parameter in the user's passwd file, you should return it as $authparam,
                    323:  i.e., the first of the variables returned by create_password().             
                    324: 
                    325: 
                    326: =cut 
1.4       raeburn   327: 
                    328: sub create_password {
1.13      albertel  329:     my ($authparam,$dom,$username) = @_;
1.4       raeburn   330:     my $authchk = 'ok';
1.11      raeburn   331:     my $newpasswd = '';
1.4       raeburn   332:     my $create_passwd = 0;
1.11      raeburn   333:     return ($authparam,$create_passwd,$authchk,$newpasswd);
1.1       raeburn   334: }
                    335: 
1.32      jms       336: =pod
                    337: 
                    338: =item instcode_format()
                    339: 
                    340:  Split coursecodes into constituent parts.   
                    341:  e.g., INSTITUTIONALCODE = fs03nop590, LON-CAPA COURSEID: 43551dedcd43febmsul1
                    342:  (MSU's course naming scheme - fs03 = Fall semester 2003, nop =
                    343:  department name, 590 = course number)
                    344: 
                    345:  Incoming data:
                    346:  $dom (domain)
                    347:  $$instcodes{'43551dedcd43febmsul1'} = 'fs03nop590' (hash of courseIDs)
                    348:  
                    349:  fs03nop590 would be split as follows
                    350:  @{$codetitles} = ("year","semester","department","number")
1.33      bisitz    351:  $$codes{'year'} = '2003'
1.32      jms       352:  $$codes{'semester'} = 'Fall'
                    353:  $$codes{'department'} = 'nop'
                    354:  $$codes{'number'} = '590'
                    355: 
                    356:  requires six arguments:
                    357:  domain ($dom)
                    358:  reference to hash of institutional course IDs ($instcodes)  
                    359:  reference to hash of codes ($codes)
                    360:  reference to array of titles ($codetitles)
                    361:  reference to hash of abbreviations used in categories
                    362:  reference to hash of arrays specifying sort order used in category titles   
                    363: 
                    364:  e.g.,     %{$$cat_titles{'Semester'}} = (
                    365:                    fs => 'Fall',
                    366:                    ss => 'Spring',
                    367:                    us => 'Summer');
                    368: 
                    369:  e.g., @{$$cat_order{'Semester'}} = ('ss','us','fs'); 
                    370:  returns 1 parameter: 'ok' if no processing errors. 
1.33      bisitz    371: 
                    372:  Detailed help:
                    373:  http://yourloncapaserver/adm/help/Institutional_Integration_Course_Codes.hlp
                    374: 
1.32      jms       375: =cut
                    376: 
1.10      raeburn   377: 
                    378: sub instcode_format () {
                    379:     my ($dom,$instcodes,$codes,$codetitles,$cat_titles,$cat_order) = @_;
                    380:     my $outcome = 'ok';
                    381:     return $outcome;
                    382: }
                    383: 
1.32      jms       384: 
                    385: =pod
                    386: 
                    387: =item institutional_photos()
                    388: 
                    389:  Called when automated enrollment manager is used to update student photos.
                    390: 
                    391:  Incoming data: six arguments
                    392:  (a) $dom (domain)
                    393:  (b) $crs (LONCAPA course number)
                    394:  (c) $affiliates: a reference to a hash with the keys set to the 
                    395:  institutional course IDs for the course.
                    396:  (d) $result: a reference to a hash which will return usernames  
                    397:      of students (& separated) in following categories (the keys):
                    398:      new, update, missing, same, deleted, noid, nouser. The list 
                    399:      includes those students for whom the result of the modification 
                    400:      process was either addition of a new photo. update of an
                    401:      existing photo, photo was found to be missing from institution's
                    402:      data store, photo used is same as before, or photo was 
                    403:      deleted from storage on LON-CAPA server housing student's
1.34    ! weissno   404:      information, no student/employee ID was available. 
1.12      raeburn   405:                
1.32      jms       406:  (e) $action: the type of action needed. (e.g., update, delete);
                    407:  (f) $students: a reference to a hash with the keys set to student 
                    408:  usernames and domains in the form username:domain, and values set
                    409:  to the studentID, if action is required for specific students.  
                    410: 
                    411:  returns 1 parameter: 'ok' if no processing errors.
                    412:  other course or student specific values can be stored as values
                    413:  in the appropriate referenced hashes. 
                    414: 
                    415: =cut
1.12      raeburn   416: 
                    417: sub institutional_photos {
                    418:     my ($dom,$crs,$affiliates,$result,$action,$students) = @_;
                    419:     my $outcome = 'ok';
                    420:     return $outcome;
                    421: }
                    422: 
1.32      jms       423: =pod
                    424: 
                    425: =item photo_permission()
                    426: 
                    427:  Incoming data: three arguments
                    428:  (a) $dom (domain)
                    429:  (b) $perm_reqd: a reference to a a scalar that is either 'yes'
                    430:  if a course owner must indicate acceptance of conditions of use,
                    431:  'no' otherwise.
                    432:  (c) $conditions: the text of the conditions of use.
                    433:     
                    434:  returns 1 parameter: 'ok' if no processing errors.
                    435:  $$perm_reqd is set to 'yes' or 'no'
                    436:  $$agreement is set to conditions of use - plain text string
                    437:              which will be displayed in a textarea in a web form.
                    438: 
                    439: 
                    440: =cut
                    441: 
1.12      raeburn   442: sub photo_permission {
                    443:    my ($dom,$perm_reqd,$conditions) = @_;
                    444:    $$perm_reqd = 'no';
                    445:    $$conditions = '';
                    446:    my $outcome = 'ok';
                    447:    return $outcome;
                    448: }
                    449: 
1.32      jms       450: =pod
                    451: 
                    452: =item manager_photo_update()
                    453: 
                    454:  Incoming data: one argument
                    455:  (a) $dom (domain)
                    456: 
                    457:  returns 2 parameters: update (0 or 1), and comment.
                    458:  Called by automated enrollment manager, to determine 
                    459:  whether "Update Student photos" button will be available,
                    460:  and if so, the message (plain text string) that will be displayed
                    461:  with the button. 
1.12      raeburn   462: 
1.32      jms       463: 
                    464: =cut
1.12      raeburn   465:                                                                                         
                    466: sub manager_photo_update {
                    467:     my ($dom) = @_;
                    468:     my $update = 0;
                    469:     my $comment = '';
                    470:     return ($update,$comment);
                    471: }
                    472: 
1.32      jms       473: =pod
                    474: 
                    475: 
                    476: =item check_section()
                    477: 
                    478:  Incoming data: three arguments (+ fourth optional argument)
                    479:  (a) $class - institutional class id (coursecode concatanated with section) 
                    480:  (b) $owner - course owner (2.2 and later username:domain; pre-2.2 username;
                    481:                             2.6 and later - comma-separated list of 
                    482:                             username:domain for course owner and co-owners.)
                    483:  (c) $dom - domain of course
                    484:  (d) $dbh - optional database handle
                    485: 
                    486:  returns 1 parameter - $sectioncheck ('ok' or other value). 
                    487:  Verifies that at least one of the course owner (or co-owners) have access 
                    488:  to classlist for specific class according to institution's SIS
                    489:  'ok' if access available  
                    490: 
                    491: 
                    492: =cut
1.16      raeburn   493: 
                    494: sub check_section {
                    495:     my ($class,$owner,$dom,$dbh) = @_;
                    496:     my $sectioncheck = 'ok';
                    497:     return $sectioncheck;
                    498: }
                    499: 
1.32      jms       500: =pod
                    501: 
                    502: =item instcode_defaults()
                    503: 
                    504:  Incoming data: three arguments
                    505:  (a) $dom - domain
                    506:  (b) $defaults - reference to hash which will contain default regular
                    507:                  expression matches for different components of an 
                    508:                  institutional course code 
                    509:  (c) $code_order - reference to array which will contain order of 
                    510:                    component parts used in institutional code.  
                    511: 
                    512:  returns 1 parameter - ('ok' or other value).
                    513:  Used to construct a regular expression to be used when searching for
                    514:  courses based on fragments of an institutional code.
                    515:  $defaults contains defaults to use for each component, and code_order
                    516:  contains keys of hash in order in which they are to be concatenated.
                    517: 
                    518:  e.g., INSTITUTIONALCODE = fs03nop590
                    519:  (MSU's course naming scheme - fs  = semester, 03 = year, nop =
                    520:  department name, 590 = course number)
                    521: 
                    522:      %{$defaults} = (
                    523:         'Year' => '\d{2}',
                    524:         'Semester' => '^[sfu]s', 
                    525:         'Department' => '\w{2,3}',
                    526:         'Number' => '\d{3,4}\w?',
                    527:      );
                    528: 
                    529:      @{$code_order} = ('Semester','Year','Department','Number');
                    530: 
1.33      bisitz    531:  Detailed help:
                    532:  http://yourloncapaserver/adm/help/Institutional_Integration_Course_Codes.hlp
                    533: 
1.32      jms       534: =cut
1.17      raeburn   535: 
                    536: sub instcode_defaults {
                    537:     my ($dom,$defaults,$code_order) = @_;
                    538:     return 'ok';
                    539: }
                    540: 
1.32      jms       541: 
                    542: =pod
                    543: 
                    544: =item allusers_info()
                    545: 
                    546:  Incoming data: three arguments
                    547:  (a) $dom - domain
                    548:  (b) $instusers - reference to hash which will contain hashes, 
                    549:                  where keys will be usernames and value will be a 
                    550:                  hash of user information. Keys in the inner hash 
                    551:                  will be some or all of: lastname,firstname,
                    552:                  middlename, generation, id, inststatus - 
                    553:                  institutional status (e.g., faculty,staff,student)
                    554:                  Values are all scalars except inststatus,
                    555:                  which is an array.
                    556:  (c) $instids - reference to hash which will contain ID numbers. 
                    557:                 keys will be unique IDs (student or faculty/staff ID)
                    558:                 values will be either: scalar (username) or an array 
                    559:                 if a single ID matches multiple usernames.
                    560:  returns 1 parameter - 'ok' if no processing error, or other value 
                    561:                        if an error occurred.
                    562:  side effects - populates the $instusers and $instids refs to hashes.
                    563:                 with information for all users from all available 
                    564:                 institutional datafeeds.
                    565: 
                    566: 
                    567: =cut
1.18      raeburn   568: 
                    569: sub allusers_info {
                    570:     my ($dom,$instusers,$instids) = @_;
                    571:     my $outcome = 'ok';
                    572:     return $outcome; 
                    573: }
                    574: 
1.32      jms       575: =pod
                    576: 
                    577: =item get_userinfo()
                    578: 
                    579:  Incoming data: four required arguments and additional optional arguments
                    580:  Two modes of operation:
                    581:  (1) Retrieves institutional data for a single user either by username
                    582:      if $uname is included as second argument, or by ID if $id is 
                    583:      included as a third argument.  Either (b) or (c) must be provided.
                    584:      (g), (h) and (i) will be undefined.
                    585:  (2) Retrieves institutional user data from search of an institutional
                    586:      directory based on a search. (g) and (h) are required.
                    587:      (i) is optional. (b) and (c) will be undefined. 
                    588: 
                    589:  (a) $dom - domain
                    590:  (b) $uname - username of user
                    591:  (c) $id - student/faculty ID of user
                    592:  (d) $instusers - reference to hash which will contain info for user
                    593:                  as key = value; keys will be one or all of:
                    594:                  lastname,firstname,middlename,generation,id,inststatus -
                    595:                  institutional status (e.g., faculty,staff,student)
                    596:                  Values are all scalars except inststatus,
                    597:                  which is an array.
                    598:  (e) $instids - reference to hash which will contain ID numbers - 
                    599:                  keys will be unique IDs (student or faculty/staff ID)  
                    600:                  values will be either: scalar (username) or an array
                    601:                  if a single ID matches multiple usernames.
                    602:  (f) $types - optional reference to array which contains 
                    603:               institutional types to check.
                    604:  (g) $srchby - optional if $uname or $id defined, otherwise required.
                    605:                Allowed values include: 1. lastfirst, 2. last, 3. uname
                    606:                corresponding to searches by 1. lastname,firstname;
                    607:                2. lastname; 3. username
                    608:  (h) $srchterm - optional if $uname or $id defined, otherwise required
                    609:                 String to search for.
                    610:  (i) $srchtype - optional. Allowed values: contains, begins (defaults
                    611:                 to exact match otherwise).
                    612: 
                    613:  returns 1 parameter - 'ok' if no processing error, or other value 
                    614:                        if an error occurred.
                    615:  side effects - populates the $instusers and $instids refs to hashes.
                    616:                 with information for specified username, or specified
                    617:                 id, if fifth argument provided, from all available, or 
                    618:                 specified (e.g., faculty only) institutional datafeeds,
                    619:                 if sixth argument provided.
                    620: 
                    621:  WARNING: You need to set $outcome to 'ok' once you have customized
                    622:           this routine to communicate with an instititional 
                    623:           directory data source, otherwise institutional directory 
                    624:           searches will always be reported as being unavailable
                    625:           in domain $dom.
                    626: 
                    627: =cut
1.18      raeburn   628: 
                    629: sub get_userinfo {
1.21      raeburn   630:     my ($dom,$uname,$id,$instusers,$instids,$types,
                    631:         $srchby,$srchterm,$srchtype) = @_;
1.24      raeburn   632:     my $outcome = 'unavailable';
1.18      raeburn   633:     return $outcome;
                    634: }
                    635: 
1.32      jms       636: =pod
                    637: 
                    638: =item inst_usertypes() 
                    639: 
                    640:  Incoming data: three arguments
                    641:  (a) $dom - domain
                    642:  (b) $usertypes - reference to hash which will contain 
                    643:                  key = value, where keys are institution 
                    644:                  affiliation types (e.g., Faculty, Student etc.)
                    645:                  and values are titles (e.g., Faculty/Academic Staff)
                    646:  (c) $order - reference to array which will contain the order in
                    647:               which institutional types should be shown
                    648:               when displaying data tables (e.g., default quotas    
                    649:               or updateable user fields (see domainprefs.pm) 
                    650:  returns 1 parameter - 'ok' if no processing error, or other value 
                    651:                         if an error occurred.
                    652: 
                    653: 
                    654: =cut
1.18      raeburn   655: 
                    656: sub inst_usertypes {
                    657:     my ($dom,$usertypes,$order) = @_;
1.20      raeburn   658:     @{$order} = ();
                    659:     %{$usertypes} = ();
1.18      raeburn   660:     my $outcome = 'ok';
                    661:     return $outcome;
                    662: }
1.17      raeburn   663: 
1.32      jms       664: =pod
                    665: 
                    666: =item username_rules()
                    667: 
                    668:  Incoming data: three arguments 
                    669:  (a) $dom - domain
                    670:  (b) $ruleshash - reference to hash containing rules
                    671:                   (a hash of a hash)
                    672:                   keys of top level hash are short names  
                    673:                    (e.g., netid, noncredit) 
                    674:                   for each key, value is a hash
                    675:                       desc => long name for rule  
                    676:                       rule => description of rule
                    677:                       authtype => (krb5,krb4,int, or loc)
                    678:                                  authentication type for rule 
                    679:                       authparm => authentication parameter for rule
                    680:                       authparmfixed => 1 if authparm used when
                    681:                           creating user for rule must be authparm  
                    682:                       authmsg => Message to display describing 
                    683:                                  authentication to use for this rule
                    684: 
                    685:  (c) $rulesorder - reference to array containing rule names 
                    686:                    in order to be displayed
                    687: 
                    688: 
                    689:   returns 'ok' if no processing error.
1.25      raeburn   690: 
1.32      jms       691: =cut
1.25      raeburn   692: 
                    693: sub username_rules {
                    694:     my ($dom,$ruleshash,$rulesorder) = @_;
                    695:     my $outcome;
                    696:     return $outcome;
                    697: }
                    698: 
1.32      jms       699: =pod
                    700: 
                    701: =item id_rules()
                    702: 
                    703:  Incoming data: three arguments
                    704:  (a) $dom - domain
                    705:  (b) $ruleshash - reference to hash containing rules
                    706:                   (a hash of a hash)
                    707:                   keys of top level hash are short names
                    708:                    (e.g., netid, noncredit)
                    709:                   for each key, value is a hash
                    710:                       desc => long name for rule
                    711:                       rule => description of rule
                    712: 
                    713:  (c) $rulesorder - reference to array containing rule names
                    714:                    in order to be displayed
                    715: 
                    716:   returns 'ok' if no processing error.
                    717: 
                    718: =cut
1.27      raeburn   719: 
1.30      raeburn   720: sub id_rules {
                    721:     my ($dom,$ruleshash,$rulesorder) = @_;
                    722:     my $outcome;
                    723:     return $outcome;
                    724: }
                    725: 
1.32      jms       726: =pod
                    727: 
                    728: =item selfcreate_rules()
                    729: 
                    730:  Incoming data: three arguments
                    731:  (a) $dom - domain
                    732:  (b) $ruleshash - reference to hash containing rules
                    733:                   (a hash of a hash)
                    734:                   keys of top level hash are short names
                    735:                    (e.g., netid)
                    736:                   for each key, value is a hash
                    737:                       desc => long name for rule
                    738:                       rule => description of rule
                    739: 
                    740:  (c) $rulesorder - reference to array containing rule names
                    741:                    in order to be displayed
                    742: 
                    743:   returns 'ok' if no processing error.
                    744: 
1.27      raeburn   745: 
1.32      jms       746: =cut
1.30      raeburn   747: 
1.31      raeburn   748: sub selfcreate_rules {
1.27      raeburn   749:     my ($dom,$ruleshash,$rulesorder) = @_;
                    750:     my $outcome;
                    751:     return $outcome;
                    752: }
                    753: 
1.32      jms       754: =pod
                    755: 
                    756: =item username_check() 
                    757: 
                    758:  Incoming data: four arguments
                    759:  (a) $dom - domain (scalar) 
                    760:  (b) $uname - username to compare against rules (scalar)
                    761:  (c) $to_check (reference to array of rule names to check)
                    762:  (d) $resultshash (reference to hash of results)
                    763:                     hash of results for rule checked
                    764:                    - keys are rule names
                    765:                    - values are: 1 or 0 (for matched or unmatched) 
                    766: 
                    767:  returns 'ok' if no processing error.
                    768: 
                    769: 
                    770: =cut
1.25      raeburn   771: 
                    772: sub username_check {
                    773:     my ($dom,$uname,$to_check,$resultshash) = @_;
                    774:     my $outcome;
                    775:     return $outcome; 
                    776: }
                    777: 
1.32      jms       778: =pod
                    779: 
                    780: =item id_check()
                    781: 
                    782:  Incoming data: four arguments
                    783:  (a) $dom - domain (scalar)
                    784:  (b) $id - ID to compare against rules (scalar)
                    785:  (c) $to_check (reference to array of rule names to check)
                    786:  (d) $resultshash (reference to hash of results)
                    787:                     hash of results for rule checked
                    788:                    - keys are rule names
                    789:                    - values are: 1 or 0 (for matched or unmatched)
                    790: 
                    791:  returns 'ok' if no processing error.
                    792: 
                    793: 
                    794: =cut
1.27      raeburn   795: 
                    796: sub id_check {
                    797:     my ($dom,$id,$to_check,$resultshash) = @_;
                    798:     my $outcome;
                    799:     return $outcome;
                    800: }
                    801: 
1.32      jms       802: =pod
                    803: 
                    804: =item selfcreate_check()
                    805: 
                    806:  Incoming data: four arguments
                    807:  (a) $dom - domain (scalar)
                    808:  (b) $selfcreatename - e-mail proposed as username (compare against rules - scalar)
                    809:  (c) $to_check (reference to array of rule names to check)
                    810:  (d) $resultshash (reference to hash of results)
                    811:                    hash of results for rule checked
                    812:                    - keys are rule names
                    813:                    - values are: 1 or 0 (for matched or unmatched)
                    814: 
                    815:  returns 'ok' if no processing error.
                    816: 
                    817: 
                    818: =cut
1.30      raeburn   819: 
1.31      raeburn   820: sub selfcreate_check {
                    821:     my ($dom,$selfcreatename,$to_check,$resultshash) = @_;
1.30      raeburn   822:     my $outcome;
                    823:     return $outcome;
                    824: }
                    825: 
1.32      jms       826: =pod
                    827: 
                    828: =item AUTOLOAD()
                    829: 
                    830:  Incoming data: none
                    831:  Returns ''
                    832: 
                    833:  Prevents errors when undefined subroutines are called in this package
                    834:  Will allow new routines added in the future to be called from lond etc.
                    835:  without the need for customized versions of local*.pm packages to be
                    836:  modified to include the new subroutines immediately.
                    837: 
                    838:  See "Programming Perl" 3rd ed. pp 296-298.   
                    839: 
                    840: =back
                    841: 
                    842: =cut
1.14      raeburn   843: 
                    844: sub AUTOLOAD {
                    845:     our $AUTOLOAD;
                    846:     return '';
                    847: }
                    848: 
1.1       raeburn   849: 1;

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