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

1.5       albertel    1: # functions to glue school database system into Lon-CAPA for 
                      2: # automated enrollment
1.55    ! raeburn     3: # $Id: localenroll.pm,v 1.54 2016/04/02 04:31:26 raeburn 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: =cut
                     45: 
1.4       raeburn    46: package localenroll;
                     47: 
                     48: use strict;
1.6       albertel   49: 
1.32      jms        50: =pod
                     51:  
                     52: =item run()
                     53:  set this to return 1 if you want the auto enrollment to run
                     54: 
                     55:  Beginning with LON-CAPA version 2.4, use of this routine is
                     56:  deprecated.  Whether or not Autoenroll.pl should run is set
                     57:  by the Domain Coordinator via "Set domain configuration",
                     58:  provided in the Domain Management section of the Main menu. 
                     59: 
                     60: =cut
1.6       albertel   61: 
1.9       raeburn    62: sub run() {
                     63:     my $dom = shift;
                     64:     return 0;
                     65: }
1.4       raeburn    66: 
1.32      jms        67: 
                     68: =pod
                     69: 
                     70: =item fetch_enrollment()
                     71: 
                     72:  connects to the institutional classlist data source,
                     73:  reads classlist data and stores in an XML file
                     74:  in /home/httpd/perl/tmp/
                     75: 
                     76:  classlist files are named as follows:
                     77: 
                     78:  DOMAIN_COURSE_INSTITUTIONALCODE_classlist.xml
                     79: 
                     80:  e.g., msu_43551dedcd43febmsul1_fs03nop590001_classlist.xml
                     81:  where DOMAIN = msu  COURSE = 43551dedcd43febmsul1 
                     82:  INSTITUTIONALCODE = fs03nop590001 
                     83:  (MSU's course naming scheme - fs03 = Fall semester 2003, nop =
                     84:  department name, 590 = course number, 001 = section number.)
                     85: 
                     86:  fetch_enrollment requires three arguments -
                     87:  $dom - DOMAIN e.g., msu
                     88:  $affiliatesref - a reference to a hash of arrays that contains LON-CAPA 
                     89:  courses that are to be updated as keys, and institutional coursecodes 
                     90:  contributing enrollment to that LON-CAPA course as elements in each array.
                     91:  $replyref - a reference to a hash that contains LON-CAPA courses
                     92:  that are to be updated as keys, and the total enrollment count in all 
                     93:  affiliated sections, as determined from institutional data as hash elements. 
                     94: 
                     95:  As an example, if fetch_enrollment is called to retrieve institutional
                     96:  classlists for a single LON-CAPA course - 43551dedcd43febmsul1 which 
                     97:  corresponds to fs03nop590, sections 001, 601 and 602 , and the course
                     98:  also accommodates enrollment from a crosslisted course in the ost
                     99:  department - fs03ost580002:
                    100: 
                    101:  the affiliatesref would be a reference to %affiliates which would be:
                    102: 
                    103:  @{$affiliates{'43551dedcd43febmsul1'}} =
                    104:    ("fs03nop590001","fs03nop590601","fs03nop590602","fs03ost580002");
                    105: 
                    106:  fetch_enrollment would create four files in /home/httpd/perl/tmp/.
                    107:  msu_43551dedcd43febmsul1_fs03nop590001_classlist.xml
                    108:  msu_43551dedcd43febmsul1_fs03nop590601_classlist.xml
                    109:  msu_43551dedcd43febmsul1_fs03nop590602_classlist.xml
                    110:  msu_43551dedcd43febmsul1_fs03ost580002_classlist.xml
                    111: 
                    112:  In each file, student data would be stored in the following format
                    113:  
                    114:  <student username="smith">
                    115:   <autharg>MSU.EDU</autharg>
                    116:   <authtype>krb4</authtype>
                    117:   <email>smith@msu.edu</email>
                    118:   <enddate></enddate>
                    119:   <firstname>John</firstname>
                    120:   <generation>II</generation>
                    121:   <groupID>fs03nop590001</groupID>
                    122:   <lastname>Smith</lastname>
                    123:   <middlename>D</middlename>
                    124:   <startdate></startdate>
                    125:   <studentID>A12345678</studentID>
1.44      raeburn   126:   <credits></credits>
                    127:   <inststatus></inststatus>
1.32      jms       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: 
1.44      raeburn   152:  The <credits> tag need only be used if the credits earned by the students will 
                    153:  be different from the default for the course. The course default is set when the
                    154:  course is created and can be modifed by a Domain Coordinator via "View or
1.50      raeburn   155:  modify a course or community" on the DC's Main Menu screen.
1.44      raeburn   156: 
                    157:  A value for <inststatus> should be the institutional status used for students,
1.50      raeburn   158:  and should be one of the types defined in the "Institutional user types"
                    159:  section in the domain config screen for:
                    160:  "Default authentication/language/timezone/portal/types" 
                    161: 
                    162:  If no status types are defined for the domain this tag can be omitted.
                    163:  If Autoupdate.pl is enabled in your domain, updates to the institutional 
                    164:  status set here will be updated by Autoupdate.pl, should changes occur.
1.44      raeburn   165: 
1.32      jms       166:  If there were 10 students in fs03nop590001, 5 students in fs03nop59o601, 
                    167:  8 students in fs03nop590602, and 2 students in fs03ost580002,
                    168:  then $$reply{'43551dedcd43febmsul1'} = 25
                    169: 
                    170:  The purpose of the %reply hash is to detect cases where the institutional 
                    171:  enrollment is 0 (most likely due to a problem with the data source).
                    172:  In such a case, the LON-CAPA course roster is left unchanged (i.e., no
                    173:  students are expired, even if automated drops is enabled.
                    174:  
                    175:  fetch_enrollment should return a 0 or 1, depending on whether a connection
                    176:  could be established to the institutional data source.
                    177:  0 is returned if no connection could be made.
                    178:  1 is returned if connection was successful
                    179: 
                    180:  A return of 1 is required for the calling modules to perform LON-CAPA
                    181:  roster changes based on the contents of the XML classlist file(s), e,g,,
                    182:  msu_43551dedcd43febmsul1_fs03nop590001_classlist.xml
                    183: 
                    184:  XML classlist files are temporary. They are deleted after the enrollment 
                    185:  update process in the calling module is complete.
                    186: 
                    187: 
                    188: =cut
1.1       raeburn   189: 
                    190: sub fetch_enrollment {
1.7       matthew   191:     my ($dom,$affiliatesref,$replyref) = @_;
                    192:     foreach my $crs (sort keys %{$affiliatesref}) {
                    193:         $$replyref{$crs} = 0;
                    194:     }
                    195:     my $okflag = 0;
                    196:     return $okflag;
1.4       raeburn   197: }
                    198: 
1.32      jms       199: =pod
                    200: 
                    201: =item get_sections()
                    202: 
                    203:  This is called by the Automated Enrollment Manager interface
                    204:  (lonpopulate.pm) to create an array of valid sections for 
                    205:  a specific institutional coursecode.
                    206:  e.g., for MSU coursecode: fs03nop590
                    207:  ("001","601","602") would be returned
                    208: 
                    209:  If the array returned contains at least one element, then 
                    210:  the interface offerred to the course coordinator, lists
                    211:  official sections and provides a checkbox to use to
                    212:  select enrollment in the LON-CAPA course from each official section.  
                    213: 
                    214:  get_sections takes two arguments - (a) the institutional coursecode
                    215:  (in the MSU case this is a concatenation of semester code, department
                    216:  and course number), and (b) the LON-CAPA domain that contains the course. 
                    217:  
                    218:  If there is no access to official course sections at your institution,
                    219:  then an empty array is returned, and the Automated Enrollment Manager
                    220:  interface will allow the course coordinator to enter section numbers
                    221:  in text boxes.
                    222:  
                    223: 
                    224: 
                    225: =cut
1.4       raeburn   226: 
                    227: sub get_sections {
1.9       raeburn   228:     my ($coursecode,$dom) = @_;
1.4       raeburn   229:     my @secs = ();
                    230:     return @secs;
1.1       raeburn   231: }
                    232: 
1.32      jms       233: =pod
                    234: 
                    235: =item new_course()
                    236: 
                    237:  This is called by loncreatecourse.pm and 
                    238:  lonpopulate.pm to record that fact that a new course section
                    239:  has been added to LON-CAPA that requires access to institutional data
                    240:  At MSU, this is required, as institutional classlists can only made
                    241:  available to faculty who are officially assigned to a course.
                    242:  
                    243:  The new_course subroutine is used to check that the course owner
                    244:  of the LON-CAPA course is permitted to access the institutional
                    245:  classlist for any course sections and crosslisted classes that
                    246:  the course coordinator wishes to have affiliated with the course.
                    247:  
                    248:  If access is permitted, then 'ok' is returned.
                    249:  The course section or crosslisted course will only be added to the list of
                    250:  affiliates if 'ok' is returned.
                    251: 
1.41      raeburn   252:  new_course takes three required arguments -
1.32      jms       253:  (a) the institutional courseID (in the MSU case this is a concatenation of 
                    254:  semester code, department code, course number, and section number
                    255:  e.g., fs03nop590001).
                    256:  (b) the course owner. This is the LON-CAPA username and domain of the course 
                    257:  coordinator assigned to the course when it is first created, in the form
                    258:  username:domain
                    259:  (c) the LON-CAPA domain that contains the course
                    260: 
1.41      raeburn   261:  new_course also takes a fourth (optional) argument -
                    262:  (d) the course co-owners, as a comma-separated list of username:domain for
                    263:  any co-owners. 
                    264: 
1.32      jms       265: =cut
1.4       raeburn   266: 
                    267: sub new_course  {
1.41      raeburn   268:     my ($course_id,$owner,$dom,$coowners) = @_;
1.4       raeburn   269:     my $outcome = 'ok';
                    270:     return $outcome;
1.1       raeburn   271: }
                    272: 
1.32      jms       273: =pod
                    274: 
                    275: =item validate_courseID()
                    276: 
                    277:  This is called whenever a new course section or crosslisted course
                    278:  is being affiliated with a LON-CAPA course (i.e., by loncreatecourse.pm
                    279:  and the Automated Enrollment Manager in lonpopulate.pm).
                    280:  A check is made that the courseID that the course coordinator wishes
                    281:  to affiliate with the course is valid according to the institutional
                    282:  schedule of official classes 
                    283: 
                    284:  A valid courseID is confirmed by returning 'ok'
                    285: 
                    286:  validate_courseID takes two arguments -
                    287:  (a) the institutional courseID (in the MSU case this is a concatenation of
                    288:  semester code, department code, course number, and section number
                    289:  e.g., fs03nop590001).
                    290:  (b) the LON-CAPA domain that contains the course
                    291: 
                    292: =cut  
1.4       raeburn   293: 
                    294: sub validate_courseID {
1.9       raeburn   295:     my ($course_id,$dom) = @_;
1.4       raeburn   296:     my $outcome = 'ok';
                    297:     return $outcome;   
                    298: }
1.1       raeburn   299: 
1.32      jms       300: =pod
                    301: 
1.36      raeburn   302: =item validate_instcode()
                    303: 
                    304: This is called when a request is being made for an official course.
                    305: A check is made that the institutional code for which a course is
                    306: is being requested is valid according to the institutional
                    307: schedule of official classes.
                    308: 
                    309: If the username of the course owner is provided, a more restrictive
                    310: test is used, namely that the requestor is listed as instructor of
                    311: record for the course in the institution's course schedule/database.
                    312: 
1.38      raeburn   313: validate_instcode takes three arguments -
1.36      raeburn   314:  (a) the LON-CAPA domain that will contain the course
                    315:  (b) the institutional code (in the MSU case this is a concatenation of
                    316:  semester code, department code, and course number, e.g., fs03nop590.
                    317:  (c) an optional institutional username for the course owner.
                    318: 
1.39      raeburn   319: An array is returned containing (a) the result of the check for a valid 
1.44      raeburn   320: instcode, (b) an (optional) course description, and (c) the default credits
                    321: earned by students when completing this course. If no institutional credits
                    322: value is available, the default credits for the course can be set via the
                    323: course request form, or via XML in a batch file, of via the web form used
                    324: by the Domain Coordinator to create new courses one at a time.
                    325: 
1.39      raeburn   326: A valid instcode is confirmed by returning 'valid'.
1.44      raeburn   327: 
1.39      raeburn   328: If no course description is available, '' should be set as
                    329: the value of the second item in the returned array.
                    330: 
1.36      raeburn   331: =cut
                    332: 
                    333: sub validate_instcode {
1.38      raeburn   334:     my ($dom,$instcode,$owner) = @_;
1.36      raeburn   335:     my $outcome = '';
1.39      raeburn   336:     my $description = '';
1.44      raeburn   337:     my $credits = '';
                    338:     return ($outcome,$description,$credits);
1.36      raeburn   339: }
                    340: 
                    341: =pod
                    342: 
1.38      raeburn   343: =item validate_crsreq()
                    344: 
                    345: This is used to check whether a course request should be processed
                    346: automatically, or held in a queue pending administrative action at
                    347: the institution.
                    348: 
                    349: Course requests will trigger this check if the process type has been set 
1.54      raeburn   350: to 'validate' for the course type (official, unofficial, textbook, 
                    351: placement or community) and the requestor's affiliation.  Whether
                    352: "validate" is an available option in the Domain Configuration menu 
                    353: is controlled by auto_courserequest_checks(). 
1.38      raeburn   354: One scenario is where the request is for an official course, in which case
                    355: a check could be made that the requestor is listed as instructor of 
                    356: record for the course in the institution's course schedule/database.
                    357: 
                    358: Other scenarios are possible, and the routine can be customized according
                    359: to whatever rules a domain wishes to implement to run validations against
                    360: given the data passed in to the routine.
                    361: 
1.51      raeburn   362: validate_crsreq takes seven arguments -
1.38      raeburn   363:  (a) the LON-CAPA domain that will contain the course.
                    364:  (b) the username:domain for the course owner.
1.54      raeburn   365:  (c) the course type (official, unofficial,textbook, placement or community)
1.38      raeburn   366:  (d) a comma-separated list of institutional affiliations of 
                    367:      the course owner.
                    368:  (e) the institutional code (in the MSU case this is a concatenation of
1.46      raeburn   369:  semester code, department code, and course number, e.g., fs03nop590).
1.38      raeburn   370:  (f) a comma-separated list of institutional sections included in
                    371:      the course request (only applicable to official courses).
1.46      raeburn   372:  (g) an optional reference to a hash of custom form data.
1.52      raeburn   373:      The custom form data will come from crsreq_updates(), with one
                    374:      additional item: $custominfo->{'_LC_clonefrom'}, provided internally
                    375:      (the courseID of the LON-CAPA course being cloned).
1.38      raeburn   376: 
                    377: A valid courserequest is confirmed by returning 'process'.
1.46      raeburn   378: The following can be returned: process, rejected, pending, approval or 
                    379: error (with error condition - no :), followed by a : and then an optional message. 
1.38      raeburn   380: 
                    381: (a) process  - the requestor is the recorded instructor - create the course
1.52      raeburn   382: 
1.40      raeburn   383: (b) rejected - the requestor should never be requesting this course, reject the
1.38      raeburn   384:     request permanently
1.52      raeburn   385: 
1.38      raeburn   386: (c) pending - the requestor is not the recorded instructor, but could
                    387:     become so after administrative action at the institution. Put the
1.46      raeburn   388:     request in a queue and, if an official course, check 
                    389:     localenroll:validate_instcode() periodically until the status changes to 
                    390:     "valid".
1.52      raeburn   391: 
1.38      raeburn   392: (d) approval - the request will be held pending review by a Domain Coordinator.
1.52      raeburn   393: 
1.38      raeburn   394: (e) error (followed by the error condition).
                    395: 
                    396: =cut
                    397: 
                    398: sub validate_crsreq {
1.46      raeburn   399:     my ($dom,$owner,$crstype,$inststatuslist,$instcode,$instseclist,$custominfo) = @_;
1.38      raeburn   400:     my $outcome = 'approval';
                    401:     return $outcome;
                    402: }
                    403: 
                    404: =pod 
                    405: 
                    406: =item crsreq_checks()
                    407: 
                    408: This is used to determine whether the "validate" option should appear in the
                    409: possible choices for course request processing in the Domain Configuration 
                    410: menu for Course Requests. Ultimately it is called by domainprefs.pm (via: 
                    411: lonnet -> lond -> localenroll.pm) The domain configuration menu includes 
1.54      raeburn   412: a table where columns are course type (official, unofficial, textbook,
                    413: placement or community) and rows are institutional affiliations 
                    414: (e.g., Faculty, Staff, Student etc.).
1.38      raeburn   415: 
1.42      raeburn   416: crsreq_checks() takes three arguments: $dom, $reqtypes, $validations.
1.38      raeburn   417: $dom - the domain for which validation options are needed.
                    418: $reqtypes - ref to an ARRAY of course types (i.e., official, unofficial and community.
                    419: $validations - ref to a hash of a hash which will determine whether "validate"
                    420: will be one of the possible choices for each course type (outer hash key),
                    421: and institutional type (inner hash key).
                    422: 
                    423: For example to allow validate to be a choice for official classes for Faculty,
                    424: req_checks would include:
                    425: 
                    426: $validations{'official'}{'Faculty'} = 1;
                    427: 
                    428: This routine is closely tied to validate_crsreq(). "Validate" should not be
                    429: a possible choice in the domain configuration menu for a particular course
                    430: type/institutional affiliation, unless a corresponding validation code has
                    431: been implemented in validate_crsreq().
                    432: 
                    433: For example at MSU, official courses requested by Faculty will be validated
                    434: against the official schedule of classes to check that the requestor is one
                    435: of the instructors of record for the course.  In this case validate_crsreq()
                    436: includes a call to validate_instcode().
                    437: 
                    438: =cut
                    439: 
                    440: sub crsreq_checks {
                    441:     my ($dom,$reqtypes,$validations) = @_;
                    442:     if ((ref($reqtypes) eq 'ARRAY') && (ref($validations) eq 'HASH')) {
                    443:         my (%usertypes,@order);
                    444:         if (&inst_usertypes($dom,\%usertypes,\@order) eq 'ok') {
                    445:             foreach my $type (@{$reqtypes}) {
                    446:                 foreach my $inst_type (@order) {
                    447:                     $validations->{$type}{$inst_type} = 0;
                    448:                 }
                    449:             }
                    450:         }
                    451:     }
                    452:     return 'ok';
                    453: }
                    454: 
1.52      raeburn   455: =pod
                    456: 
                    457: =item crsreq_updates()
                    458: 
                    459: This is used to customize the LON-CAPA course request process.
                    460: There are two hash references: $incoming, and $outgoing; $incoming can
                    461: contain additional information collected from the requester, whereas $outgoing
                    462: can contain custom items to send back to lonrequestcourse.pm, which creates the
                    463: HTML displayed to the user during a course request.
                    464: 
                    465: Different key-value pairs may be returned to lonrequestcourse.pm in the $outgoing
                    466: hashref depending on the current action.  The available actions are:
                    467: review, prevalidate, process, created and queued.
                    468: 
                    469: One scenario would be to return HTML markup in: $outgoing->{'reviewweb'},
                    470: i.e., where the action is 'review', to prompt the user to provide additional
                    471: information as part of the course request, at the request review stage, 
                    472: (i.e,, the page which contains the button used to submit a completed course request).
                    473: 
                    474: The HTML could contain form elements (e.g., radio buttons etc.). The value(s)
                    475: selected by the requester in those form elements will be available in the incoming
                    476: hashref, for a subsequent action, if the corresponding keys have been included
                    477: in $outgoing->{'formitems'}, i.e., $outgoing will be hash of a hash.  If a
                    478: particular form item will the single valued, the value set for the key in the 
                    479: inner hash in $outgoing should be 1, otherwise, if it will be multi-valued,
                    480: the value should be multiple.
                    481: 
                    482: The $outgoing hashref can contain a 'formitems' key for both the prevalidate
                    483: and process actions, as calls to localenroll::crsreq_update() can originate
                    484: in lonrequestcourse::process_request() for both of those actions.
                    485: 
                    486: The retrieved form values are passed to localenroll::validate_crsreq() as the
                    487: optional seventh arg (a hashref) -- $custominfo.
                    488: 
                    489: =cut
                    490: 
1.45      raeburn   491: sub crsreq_updates {
                    492:     my ($cdom,$cnum,$crstype,$action,$ownername,$ownerdomain,$fullname,$title,
1.47      raeburn   493:         $code,$accessstart,$accessend,$incoming,$outgoing) = @_;
1.45      raeburn   494:     unless (ref($outgoing) eq 'HASH') {
                    495:         return 'fail';
                    496:     }
                    497:     my %extrainfo;
                    498:     if (ref($incoming) eq 'HASH') {
                    499:         %extrainfo = %{$incoming};
                    500:     }
                    501:     if ($action eq 'review') {
                    502:         $outgoing->{'reviewweb'} = '';
1.46      raeburn   503:     } elsif ($action eq 'prevalidate') {
                    504:         $outgoing->{'formitems'} = {}; # key=>value, where key is form element name
                    505:                                        #             and value is multiple, if there
                    506:                                        #             are multiple form elements with
                    507:                                        #             the same name.
1.45      raeburn   508:     } elsif ($action eq 'process') {
                    509:         $outgoing->{'formitems'} = {}; # key=>value, where key is form element name
                    510:                                        #             and value is multiple, if there
                    511:                                        #             are multiple form elements with
1.46      raeburn   512:                                        #             the same name.
1.45      raeburn   513:     } elsif ($action eq 'created') {
                    514:         $outgoing->{'createdweb'} = '';
                    515:         $outgoing->{'createdmsg'} = [{
                    516:                                      mt => '',
                    517:                                      args => [],
                    518:                                     }];
1.48      raeburn   519:         $outgoing->{'createdactions'} = {
                    520:                                             environment => {},
                    521:                                         };
                    522:                                         # environment can contain key=>value for
                    523:                                         # items to set in the course environment.
                    524:                                         # These would be items which are NOT included
                    525:                                         # in the items set via options in the course
                    526:                                         # request form. Currently self-enrollment
                    527:                                         # settings are the only ones allowed, i.e.,
                    528:                                         # internal.selfenroll_types internal.selfenroll_registered
                    529:                                         # internal.selfenroll_section internal.selfenroll_start_access 
                    530:                                         # internal.selfenroll_end_access internal.selfenroll_limit
                    531:                                         # internal.selfenroll_cap internal.selfenroll_approval
                    532:                                         # internal.selfenroll_notifylist
1.45      raeburn   533:     } elsif ($action eq 'queued') {
1.46      raeburn   534:         $outgoing->{'queuedmsg'} = [{
                    535:                                      mt   => '',
1.45      raeburn   536:                                      args => [],
                    537:                                     }];
                    538:         $outgoing->{'queuedweb'} = '';
                    539:     }
                    540:     return 'ok'
                    541: }
                    542: 
1.38      raeburn   543: =pod
                    544: 
1.55    ! raeburn   545: =item export_grades()
        !           546:  
        !           547: This routine can be customized to push grade information to some other gradebook,
        !           548: LCMS, or administrative system external to LON-CAPA.
        !           549: 
        !           550: export_grades() takes five arguments -
        !           551: (a) the LON-CAPA course ID
        !           552: (b) the LON-CAPA course domain
        !           553: (c) a hash reference containing the following: 
        !           554:     scope    => scope of the grades (e.g., course, map or resource).
        !           555:     instcode => institutional course code (if an official course)
        !           556:     crstype  => course type -- Course, Community or Placement
        !           557:     context  => calling context, e.g., "completion" when a student completes a placement test.
        !           558: (d) a perl data structure (hash of a hash) containing the grade data.
        !           559:     in the outer hash, the keys are student's username:domain
        !           560:     in the inner hash, keys are:  
        !           561:     id        => student/employee ID
        !           562:     lastname  => student's last name
        !           563:     firstname => student's first name
        !           564:     email     => student's "permannent" e-mail address
        !           565:     section   => student's LON-CAPA course section
        !           566:     total     => total points earned
        !           567:     bytitle   => reference to a hash (keys are question titles, values are points
        !           568:     bysymb    => reference to a hash (keys are symbs, i.e., unique resource identifiers).
        !           569: (e) reference to a hash which will contain information to return.
        !           570:     keys will be the student's username:domain. Value of 1 to show grades pushed 
        !           571:     successfully. 
        !           572: 
        !           573: =cut
        !           574: 
        !           575: sub export_grades
        !           576:     my ($cnum,$cdom,$hashref,$dataref,$outgoing) = @_;
        !           577:     my %info;
        !           578:     if (ref($hashref) eq 'HASH') {
        !           579:         %info = %{$hashref};
        !           580:     }
        !           581:     if ((ref($dataref) eq 'HASH') && (ref($outgoing) eq 'HASH')) {
        !           582:         foreach my $key (keys(%{$dataref})) {
        !           583:             $outgoing->{$key} = 1;
        !           584:         }
        !           585:         return 'ok';
        !           586:     } else {
        !           587:         return 'error';
        !           588:     }
        !           589: }
        !           590: 
        !           591: =pod
        !           592: 
1.32      jms       593: =item create_password()
                    594: 
                    595:  This is called when the authentication method set for the automated 
                    596:  enrollment process when enrolling new users in the domain is "localauth".
                    597:  This could be signalled for the specific user by the value of localauth
                    598:  for the <authtype> tag from the classlist.xml files, or if this is blank,
                    599:  the default authtype, set by the domain coordinator when creating the course
                    600:  with loncreatecourse.pm.
                    601:   
                    602:  create_password takes three arguments -
                    603:  (a) $authparam - the value of <autharg> from the classlist.xml files,
                    604:  or if this blank, the default autharg, set by the domain coordinator when 
                    605:  creating the course with loncreatecourse.pm
                    606:  (b) $dom - the domain of the new user.
                    607:  (c) $username - the username of the new user (currently not actually used)
                    608: 
                    609:  Four values are returned:
                    610:  (a) the value of $authparam - which might have been changed
                    611:  (b) a flag to indicate whether a password had been created
                    612:  0 means no password created
                    613:  1 means password created.  In this case the calling module - Enrollment.pm
                    614:  will send the LON-CAPA username and password to the new user's e-mail
                    615:  (if one was provided), or to the course owner (if one was not provided and
                    616:  the new user was created by the automated process), or to the active
                    617:  course coordinator (if the new user was created using the 'update roster
                    618:  now' interface included in the Automated Enrollment Manager).  
                    619:  (c) a flag to indicate that the authentication method is correct - 'ok'.
                    620:  If $authchk is not set to 'ok' then account creation and enrollment of the 
                    621:  new user will not occur.
                    622:  (d) if a password was created it can be sent along.  This is the password 
                    623:  which will be included in the e-mail sent to the new user, or made available    
                    624:  to the course owner/course coordinator if no e-mail address is provided. If
                    625:  you do not wish to send a password, but want to give instructions on obtaining
                    626:  one, you could set $newpasswd as those instructions. (e.g.,
                    627:  $newpasswd = '(Please visit room 212, ACNS Bldg. to obtain your password)';
                    628:  The value of $newpasswd is NOT written in the user's LON-CAPA passwd file in
                    629:  /home/httpd/lonUsers/$dom/a/b/c/abcuser/passwd, which in the case of a user
                    630:  employing localauth will contain 'localauth:$authparam'.  If you need to include
                    631:  a parameter in the user's passwd file, you should return it as $authparam,
                    632:  i.e., the first of the variables returned by create_password().             
                    633: 
                    634: 
                    635: =cut 
1.4       raeburn   636: 
                    637: sub create_password {
1.13      albertel  638:     my ($authparam,$dom,$username) = @_;
1.4       raeburn   639:     my $authchk = 'ok';
1.11      raeburn   640:     my $newpasswd = '';
1.4       raeburn   641:     my $create_passwd = 0;
1.11      raeburn   642:     return ($authparam,$create_passwd,$authchk,$newpasswd);
1.1       raeburn   643: }
                    644: 
1.32      jms       645: =pod
                    646: 
                    647: =item instcode_format()
                    648: 
                    649:  Split coursecodes into constituent parts.   
                    650:  e.g., INSTITUTIONALCODE = fs03nop590, LON-CAPA COURSEID: 43551dedcd43febmsul1
                    651:  (MSU's course naming scheme - fs03 = Fall semester 2003, nop =
                    652:  department name, 590 = course number)
                    653: 
                    654:  Incoming data:
                    655:  $dom (domain)
                    656:  $$instcodes{'43551dedcd43febmsul1'} = 'fs03nop590' (hash of courseIDs)
                    657:  
                    658:  fs03nop590 would be split as follows
                    659:  @{$codetitles} = ("year","semester","department","number")
1.33      bisitz    660:  $$codes{'year'} = '2003'
1.32      jms       661:  $$codes{'semester'} = 'Fall'
                    662:  $$codes{'department'} = 'nop'
                    663:  $$codes{'number'} = '590'
                    664: 
                    665:  requires six arguments:
                    666:  domain ($dom)
                    667:  reference to hash of institutional course IDs ($instcodes)  
                    668:  reference to hash of codes ($codes)
                    669:  reference to array of titles ($codetitles)
                    670:  reference to hash of abbreviations used in categories
                    671:  reference to hash of arrays specifying sort order used in category titles   
                    672: 
                    673:  e.g.,     %{$$cat_titles{'Semester'}} = (
                    674:                    fs => 'Fall',
                    675:                    ss => 'Spring',
                    676:                    us => 'Summer');
                    677: 
                    678:  e.g., @{$$cat_order{'Semester'}} = ('ss','us','fs'); 
                    679:  returns 1 parameter: 'ok' if no processing errors. 
1.33      bisitz    680: 
                    681:  Detailed help:
                    682:  http://yourloncapaserver/adm/help/Institutional_Integration_Course_Codes.hlp
                    683: 
1.32      jms       684: =cut
                    685: 
1.10      raeburn   686: 
                    687: sub instcode_format () {
                    688:     my ($dom,$instcodes,$codes,$codetitles,$cat_titles,$cat_order) = @_;
                    689:     my $outcome = 'ok';
                    690:     return $outcome;
                    691: }
                    692: 
1.35      raeburn   693: =pod
                    694: 
                    695: =item possible_instcodes()
                    696: 
                    697: Gather acceptable values for institutional categories to use in course creation request form for official courses.
                    698: 
1.40      raeburn   699:  requires five arguments:
                    700: 
1.35      raeburn   701:  domain ($dom)
                    702:  reference to array of titles ($codetitles)
                    703:  reference to hash of abbreviations used in categories ($cat_titles).
1.40      raeburn   704:  reference to hash of arrays specifying sort order used in 
                    705:            category titles ($cat_order).
                    706:  reference to array which will contain order of component parts used 
                    707:            in institutional code ($code_order).
1.35      raeburn   708: 
                    709:  e.g., 
1.40      raeburn   710:  @{$codetitles} = ('Year','Semester',"Department','Number');
1.35      raeburn   711: 
                    712:  %{$$cat_titles{'Semester'}} = (
                    713:                    fs => 'Fall',
                    714:                    ss => 'Spring',
                    715:                    us => 'Summer');
                    716: 
                    717:  @{$$cat_order{'Semester'}} = ('ss','us','fs');
1.40      raeburn   718:  @{$code_order} = ('Semester','Year','Department','Number');
1.35      raeburn   719: 
                    720:  returns 1 parameter: 'ok' if no processing errors.
                    721: 
                    722: =cut
                    723: 
                    724: sub possible_instcodes {
1.40      raeburn   725:     my ($dom,$codetitles,$cat_titles,$cat_order,$code_order) = @_;
1.35      raeburn   726:     @{$codetitles} = ();
                    727:     %{$$cat_titles{'Semester'}} = ();
                    728:     @{$$cat_order{'Semester'}} = ('ss','us','fs');
1.40      raeburn   729:     @{$code_order} = ();
1.35      raeburn   730:     return 'ok';
                    731: }
                    732: 
                    733: 
1.32      jms       734: =pod
                    735: 
                    736: =item institutional_photos()
                    737: 
                    738:  Called when automated enrollment manager is used to update student photos.
                    739: 
                    740:  Incoming data: six arguments
                    741:  (a) $dom (domain)
                    742:  (b) $crs (LONCAPA course number)
                    743:  (c) $affiliates: a reference to a hash with the keys set to the 
                    744:  institutional course IDs for the course.
                    745:  (d) $result: a reference to a hash which will return usernames  
                    746:      of students (& separated) in following categories (the keys):
                    747:      new, update, missing, same, deleted, noid, nouser. The list 
                    748:      includes those students for whom the result of the modification 
                    749:      process was either addition of a new photo. update of an
                    750:      existing photo, photo was found to be missing from institution's
                    751:      data store, photo used is same as before, or photo was 
                    752:      deleted from storage on LON-CAPA server housing student's
1.34      weissno   753:      information, no student/employee ID was available. 
1.12      raeburn   754:                
1.32      jms       755:  (e) $action: the type of action needed. (e.g., update, delete);
                    756:  (f) $students: a reference to a hash with the keys set to student 
                    757:  usernames and domains in the form username:domain, and values set
                    758:  to the studentID, if action is required for specific students.  
                    759: 
                    760:  returns 1 parameter: 'ok' if no processing errors.
                    761:  other course or student specific values can be stored as values
                    762:  in the appropriate referenced hashes. 
                    763: 
                    764: =cut
1.12      raeburn   765: 
                    766: sub institutional_photos {
                    767:     my ($dom,$crs,$affiliates,$result,$action,$students) = @_;
                    768:     my $outcome = 'ok';
                    769:     return $outcome;
                    770: }
                    771: 
1.32      jms       772: =pod
                    773: 
                    774: =item photo_permission()
                    775: 
                    776:  Incoming data: three arguments
                    777:  (a) $dom (domain)
                    778:  (b) $perm_reqd: a reference to a a scalar that is either 'yes'
                    779:  if a course owner must indicate acceptance of conditions of use,
                    780:  'no' otherwise.
                    781:  (c) $conditions: the text of the conditions of use.
                    782:     
                    783:  returns 1 parameter: 'ok' if no processing errors.
                    784:  $$perm_reqd is set to 'yes' or 'no'
                    785:  $$agreement is set to conditions of use - plain text string
                    786:              which will be displayed in a textarea in a web form.
                    787: 
                    788: 
                    789: =cut
                    790: 
1.12      raeburn   791: sub photo_permission {
                    792:    my ($dom,$perm_reqd,$conditions) = @_;
                    793:    $$perm_reqd = 'no';
                    794:    $$conditions = '';
                    795:    my $outcome = 'ok';
                    796:    return $outcome;
                    797: }
                    798: 
1.32      jms       799: =pod
                    800: 
                    801: =item manager_photo_update()
                    802: 
                    803:  Incoming data: one argument
                    804:  (a) $dom (domain)
                    805: 
                    806:  returns 2 parameters: update (0 or 1), and comment.
                    807:  Called by automated enrollment manager, to determine 
                    808:  whether "Update Student photos" button will be available,
                    809:  and if so, the message (plain text string) that will be displayed
                    810:  with the button. 
1.12      raeburn   811: 
1.32      jms       812: 
                    813: =cut
1.12      raeburn   814:                                                                                         
                    815: sub manager_photo_update {
                    816:     my ($dom) = @_;
                    817:     my $update = 0;
                    818:     my $comment = '';
                    819:     return ($update,$comment);
                    820: }
                    821: 
1.32      jms       822: =pod
                    823: 
                    824: 
                    825: =item check_section()
                    826: 
                    827:  Incoming data: three arguments (+ fourth optional argument)
                    828:  (a) $class - institutional class id (coursecode concatanated with section) 
                    829:  (b) $owner - course owner (2.2 and later username:domain; pre-2.2 username;
                    830:                             2.6 and later - comma-separated list of 
                    831:                             username:domain for course owner and co-owners.)
                    832:  (c) $dom - domain of course
                    833:  (d) $dbh - optional database handle
                    834: 
                    835:  returns 1 parameter - $sectioncheck ('ok' or other value). 
                    836:  Verifies that at least one of the course owner (or co-owners) have access 
                    837:  to classlist for specific class according to institution's SIS
                    838:  'ok' if access available  
                    839: 
                    840: 
                    841: =cut
1.16      raeburn   842: 
                    843: sub check_section {
                    844:     my ($class,$owner,$dom,$dbh) = @_;
                    845:     my $sectioncheck = 'ok';
                    846:     return $sectioncheck;
                    847: }
                    848: 
1.32      jms       849: =pod
                    850: 
                    851: =item instcode_defaults()
                    852: 
                    853:  Incoming data: three arguments
                    854:  (a) $dom - domain
                    855:  (b) $defaults - reference to hash which will contain default regular
                    856:                  expression matches for different components of an 
                    857:                  institutional course code 
                    858:  (c) $code_order - reference to array which will contain order of 
                    859:                    component parts used in institutional code.  
                    860: 
                    861:  returns 1 parameter - ('ok' or other value).
                    862:  Used to construct a regular expression to be used when searching for
                    863:  courses based on fragments of an institutional code.
                    864:  $defaults contains defaults to use for each component, and code_order
                    865:  contains keys of hash in order in which they are to be concatenated.
                    866: 
                    867:  e.g., INSTITUTIONALCODE = fs03nop590
                    868:  (MSU's course naming scheme - fs  = semester, 03 = year, nop =
                    869:  department name, 590 = course number)
                    870: 
                    871:      %{$defaults} = (
                    872:         'Year' => '\d{2}',
                    873:         'Semester' => '^[sfu]s', 
                    874:         'Department' => '\w{2,3}',
                    875:         'Number' => '\d{3,4}\w?',
                    876:      );
                    877: 
                    878:      @{$code_order} = ('Semester','Year','Department','Number');
                    879: 
1.33      bisitz    880:  Detailed help:
                    881:  http://yourloncapaserver/adm/help/Institutional_Integration_Course_Codes.hlp
                    882: 
1.32      jms       883: =cut
1.17      raeburn   884: 
                    885: sub instcode_defaults {
                    886:     my ($dom,$defaults,$code_order) = @_;
                    887:     return 'ok';
                    888: }
                    889: 
1.32      jms       890: 
                    891: =pod
                    892: 
                    893: =item allusers_info()
                    894: 
                    895:  Incoming data: three arguments
                    896:  (a) $dom - domain
                    897:  (b) $instusers - reference to hash which will contain hashes, 
                    898:                  where keys will be usernames and value will be a 
                    899:                  hash of user information. Keys in the inner hash 
                    900:                  will be some or all of: lastname,firstname,
                    901:                  middlename, generation, id, inststatus - 
                    902:                  institutional status (e.g., faculty,staff,student)
                    903:                  Values are all scalars except inststatus,
                    904:                  which is an array.
                    905:  (c) $instids - reference to hash which will contain ID numbers. 
                    906:                 keys will be unique IDs (student or faculty/staff ID)
                    907:                 values will be either: scalar (username) or an array 
                    908:                 if a single ID matches multiple usernames.
1.43      raeburn   909:  (d) $lc_users - reference to hash containing LON-CAPA usernames in 
                    910:                  in domain $dom, as keys. Needed if institutional
                    911:                  data source only allows query by username.
1.32      jms       912:  returns 1 parameter - 'ok' if no processing error, or other value 
                    913:                        if an error occurred.
                    914:  side effects - populates the $instusers and $instids refs to hashes.
                    915:                 with information for all users from all available 
                    916:                 institutional datafeeds.
                    917: 
                    918: 
                    919: =cut
1.18      raeburn   920: 
                    921: sub allusers_info {
1.43      raeburn   922:     my ($dom,$instusers,$instids,$lc_users) = @_;
1.18      raeburn   923:     my $outcome = 'ok';
                    924:     return $outcome; 
                    925: }
                    926: 
1.32      jms       927: =pod
                    928: 
                    929: =item get_userinfo()
                    930: 
                    931:  Incoming data: four required arguments and additional optional arguments
                    932:  Two modes of operation:
                    933:  (1) Retrieves institutional data for a single user either by username
                    934:      if $uname is included as second argument, or by ID if $id is 
                    935:      included as a third argument.  Either (b) or (c) must be provided.
                    936:      (g), (h) and (i) will be undefined.
                    937:  (2) Retrieves institutional user data from search of an institutional
                    938:      directory based on a search. (g) and (h) are required.
                    939:      (i) is optional. (b) and (c) will be undefined. 
                    940: 
                    941:  (a) $dom - domain
                    942:  (b) $uname - username of user
                    943:  (c) $id - student/faculty ID of user
                    944:  (d) $instusers - reference to hash which will contain info for user
                    945:                  as key = value; keys will be one or all of:
                    946:                  lastname,firstname,middlename,generation,id,inststatus -
                    947:                  institutional status (e.g., faculty,staff,student)
                    948:                  Values are all scalars except inststatus,
                    949:                  which is an array.
                    950:  (e) $instids - reference to hash which will contain ID numbers - 
                    951:                  keys will be unique IDs (student or faculty/staff ID)  
                    952:                  values will be either: scalar (username) or an array
                    953:                  if a single ID matches multiple usernames.
                    954:  (f) $types - optional reference to array which contains 
                    955:               institutional types to check.
                    956:  (g) $srchby - optional if $uname or $id defined, otherwise required.
                    957:                Allowed values include: 1. lastfirst, 2. last, 3. uname
                    958:                corresponding to searches by 1. lastname,firstname;
                    959:                2. lastname; 3. username
                    960:  (h) $srchterm - optional if $uname or $id defined, otherwise required
                    961:                 String to search for.
                    962:  (i) $srchtype - optional. Allowed values: contains, begins (defaults
                    963:                 to exact match otherwise).
                    964: 
                    965:  returns 1 parameter - 'ok' if no processing error, or other value 
                    966:                        if an error occurred.
                    967:  side effects - populates the $instusers and $instids refs to hashes.
                    968:                 with information for specified username, or specified
                    969:                 id, if fifth argument provided, from all available, or 
                    970:                 specified (e.g., faculty only) institutional datafeeds,
                    971:                 if sixth argument provided.
                    972: 
                    973:  WARNING: You need to set $outcome to 'ok' once you have customized
                    974:           this routine to communicate with an instititional 
                    975:           directory data source, otherwise institutional directory 
                    976:           searches will always be reported as being unavailable
                    977:           in domain $dom.
                    978: 
                    979: =cut
1.18      raeburn   980: 
                    981: sub get_userinfo {
1.21      raeburn   982:     my ($dom,$uname,$id,$instusers,$instids,$types,
                    983:         $srchby,$srchterm,$srchtype) = @_;
1.24      raeburn   984:     my $outcome = 'unavailable';
1.18      raeburn   985:     return $outcome;
                    986: }
                    987: 
1.32      jms       988: =pod
                    989: 
1.53      raeburn   990: =item get_multusersinfo
                    991: 
                    992:  (a) $dom - domain
                    993:  (b) $type - username or id
                    994:  (c) $unamenames - reference to hash containing usernames of users
                    995:  (d) $instusers - reference to hash which will contain info for user
                    996:                  as key = value; keys will be one or all of:
                    997:                  lastname,firstname,middlename,generation,id,inststatus -
                    998:                  institutional status (e.g., faculty,staff,student)
                    999:                  Values are all scalars except inststatus,
                   1000:                  which is an array.
                   1001:  (e) $instids - reference to hash which will contain ID numbers -
                   1002:                  keys will be unique IDs (student or faculty/staff ID)
                   1003:                  values will be either: scalar (username) or an array
                   1004:                  if a single ID matches multiple usernames.
                   1005: 
                   1006:  returns 1 parameter - 'ok' if no processing error, or other value
                   1007:                        if an error occurred.
                   1008: 
                   1009:  side effects - populates the $instusers and $instids refs to hashes.
                   1010:                 with information for specified username, or specified
                   1011:                 id, if fifth argument provided, from all available, or
                   1012:                 specified (e.g., faculty only) institutional datafeeds,
                   1013:                 if sixth argument provided.
                   1014: 
                   1015:  WARNING: You need to set $outcome to 'ok' once you have customized
                   1016:           this routine to communicate with an instititional
                   1017:           directory data source, otherwise retrieval of institutional
                   1018:           user information will always be reported as being unavailable
                   1019:           in domain $dom.
                   1020: 
                   1021: =cut
                   1022: 
                   1023: sub get_multusersinfo {
                   1024:     my ($dom,$type,$usernames,$instusers,$instids) = @_;
                   1025:     my $outcome = 'unavailable'; 
                   1026:     return $outcome;
                   1027: }
                   1028: 
                   1029: =pod
                   1030: 
1.32      jms      1031: =item inst_usertypes() 
                   1032: 
1.49      raeburn  1033:  Starting with LON-CAPA 2.11.0 use of this subroutine
                   1034:  is deprecated. The domain configuration web GUI
                   1035:  accessible to Domain Coordinators will be used to
                   1036:  manage institutional types.  If you have previously
                   1037:  customized this routine, then values set there will
                   1038:  be used when displaying the "Institutional user types"
                   1039:  section in the domain config screen for:
                   1040:  "Default authentication/language/timezone/portal/types".
                   1041: 
                   1042:  Once you have visited that screen and saved the settings,
                   1043:  configuration thereafter will be via the web GUI of
                   1044:  values stored in the domain's configuration.db file on
                   1045:  the primary library server in the domain, and values in
                   1046:  inst_usertypes() will no longer be consulted.
                   1047:  
1.32      jms      1048:  Incoming data: three arguments
                   1049:  (a) $dom - domain
                   1050:  (b) $usertypes - reference to hash which will contain 
                   1051:                  key = value, where keys are institution 
                   1052:                  affiliation types (e.g., Faculty, Student etc.)
                   1053:                  and values are titles (e.g., Faculty/Academic Staff)
                   1054:  (c) $order - reference to array which will contain the order in
                   1055:               which institutional types should be shown
                   1056:               when displaying data tables (e.g., default quotas    
                   1057:               or updateable user fields (see domainprefs.pm) 
                   1058:  returns 1 parameter - 'ok' if no processing error, or other value 
                   1059:                         if an error occurred.
                   1060: 
                   1061: 
                   1062: =cut
1.18      raeburn  1063: 
                   1064: sub inst_usertypes {
                   1065:     my ($dom,$usertypes,$order) = @_;
1.20      raeburn  1066:     @{$order} = ();
                   1067:     %{$usertypes} = ();
1.18      raeburn  1068:     my $outcome = 'ok';
                   1069:     return $outcome;
                   1070: }
1.17      raeburn  1071: 
1.32      jms      1072: =pod
                   1073: 
                   1074: =item username_rules()
                   1075: 
                   1076:  Incoming data: three arguments 
                   1077:  (a) $dom - domain
                   1078:  (b) $ruleshash - reference to hash containing rules
                   1079:                   (a hash of a hash)
                   1080:                   keys of top level hash are short names  
                   1081:                    (e.g., netid, noncredit) 
                   1082:                   for each key, value is a hash
                   1083:                       desc => long name for rule  
                   1084:                       rule => description of rule
                   1085:                       authtype => (krb5,krb4,int, or loc)
                   1086:                                  authentication type for rule 
                   1087:                       authparm => authentication parameter for rule
                   1088:                       authparmfixed => 1 if authparm used when
                   1089:                           creating user for rule must be authparm  
                   1090:                       authmsg => Message to display describing 
                   1091:                                  authentication to use for this rule
                   1092: 
                   1093:  (c) $rulesorder - reference to array containing rule names 
                   1094:                    in order to be displayed
                   1095: 
                   1096: 
                   1097:   returns 'ok' if no processing error.
1.25      raeburn  1098: 
1.32      jms      1099: =cut
1.25      raeburn  1100: 
                   1101: sub username_rules {
                   1102:     my ($dom,$ruleshash,$rulesorder) = @_;
                   1103:     my $outcome;
                   1104:     return $outcome;
                   1105: }
                   1106: 
1.32      jms      1107: =pod
                   1108: 
                   1109: =item id_rules()
                   1110: 
                   1111:  Incoming data: three arguments
                   1112:  (a) $dom - domain
                   1113:  (b) $ruleshash - reference to hash containing rules
                   1114:                   (a hash of a hash)
                   1115:                   keys of top level hash are short names
                   1116:                    (e.g., netid, noncredit)
                   1117:                   for each key, value is a hash
                   1118:                       desc => long name for rule
                   1119:                       rule => description of rule
                   1120: 
                   1121:  (c) $rulesorder - reference to array containing rule names
                   1122:                    in order to be displayed
                   1123: 
                   1124:   returns 'ok' if no processing error.
                   1125: 
                   1126: =cut
1.27      raeburn  1127: 
1.30      raeburn  1128: sub id_rules {
                   1129:     my ($dom,$ruleshash,$rulesorder) = @_;
                   1130:     my $outcome;
                   1131:     return $outcome;
                   1132: }
                   1133: 
1.32      jms      1134: =pod
                   1135: 
                   1136: =item selfcreate_rules()
                   1137: 
                   1138:  Incoming data: three arguments
                   1139:  (a) $dom - domain
                   1140:  (b) $ruleshash - reference to hash containing rules
                   1141:                   (a hash of a hash)
                   1142:                   keys of top level hash are short names
                   1143:                    (e.g., netid)
                   1144:                   for each key, value is a hash
                   1145:                       desc => long name for rule
                   1146:                       rule => description of rule
                   1147: 
                   1148:  (c) $rulesorder - reference to array containing rule names
                   1149:                    in order to be displayed
                   1150: 
                   1151:   returns 'ok' if no processing error.
                   1152: 
1.27      raeburn  1153: 
1.32      jms      1154: =cut
1.30      raeburn  1155: 
1.31      raeburn  1156: sub selfcreate_rules {
1.27      raeburn  1157:     my ($dom,$ruleshash,$rulesorder) = @_;
                   1158:     my $outcome;
                   1159:     return $outcome;
                   1160: }
                   1161: 
1.32      jms      1162: =pod
                   1163: 
                   1164: =item username_check() 
                   1165: 
                   1166:  Incoming data: four arguments
                   1167:  (a) $dom - domain (scalar) 
                   1168:  (b) $uname - username to compare against rules (scalar)
                   1169:  (c) $to_check (reference to array of rule names to check)
                   1170:  (d) $resultshash (reference to hash of results)
                   1171:                     hash of results for rule checked
                   1172:                    - keys are rule names
                   1173:                    - values are: 1 or 0 (for matched or unmatched) 
                   1174: 
                   1175:  returns 'ok' if no processing error.
                   1176: 
                   1177: 
                   1178: =cut
1.25      raeburn  1179: 
                   1180: sub username_check {
                   1181:     my ($dom,$uname,$to_check,$resultshash) = @_;
                   1182:     my $outcome;
                   1183:     return $outcome; 
                   1184: }
                   1185: 
1.32      jms      1186: =pod
                   1187: 
                   1188: =item id_check()
                   1189: 
                   1190:  Incoming data: four arguments
                   1191:  (a) $dom - domain (scalar)
                   1192:  (b) $id - ID to compare against rules (scalar)
                   1193:  (c) $to_check (reference to array of rule names to check)
                   1194:  (d) $resultshash (reference to hash of results)
                   1195:                     hash of results for rule checked
                   1196:                    - keys are rule names
                   1197:                    - values are: 1 or 0 (for matched or unmatched)
                   1198: 
                   1199:  returns 'ok' if no processing error.
                   1200: 
                   1201: 
                   1202: =cut
1.27      raeburn  1203: 
                   1204: sub id_check {
                   1205:     my ($dom,$id,$to_check,$resultshash) = @_;
                   1206:     my $outcome;
                   1207:     return $outcome;
                   1208: }
                   1209: 
1.32      jms      1210: =pod
                   1211: 
                   1212: =item selfcreate_check()
                   1213: 
                   1214:  Incoming data: four arguments
                   1215:  (a) $dom - domain (scalar)
                   1216:  (b) $selfcreatename - e-mail proposed as username (compare against rules - scalar)
                   1217:  (c) $to_check (reference to array of rule names to check)
                   1218:  (d) $resultshash (reference to hash of results)
                   1219:                    hash of results for rule checked
                   1220:                    - keys are rule names
                   1221:                    - values are: 1 or 0 (for matched or unmatched)
                   1222: 
                   1223:  returns 'ok' if no processing error.
                   1224: 
                   1225: 
                   1226: =cut
1.30      raeburn  1227: 
1.31      raeburn  1228: sub selfcreate_check {
                   1229:     my ($dom,$selfcreatename,$to_check,$resultshash) = @_;
1.30      raeburn  1230:     my $outcome;
                   1231:     return $outcome;
                   1232: }
                   1233: 
1.32      jms      1234: =pod
                   1235: 
                   1236: =item AUTOLOAD()
                   1237: 
                   1238:  Incoming data: none
                   1239:  Returns ''
                   1240: 
                   1241:  Prevents errors when undefined subroutines are called in this package
                   1242:  Will allow new routines added in the future to be called from lond etc.
                   1243:  without the need for customized versions of local*.pm packages to be
                   1244:  modified to include the new subroutines immediately.
                   1245: 
                   1246:  See "Programming Perl" 3rd ed. pp 296-298.   
                   1247: 
                   1248: =back
                   1249: 
                   1250: =cut
1.14      raeburn  1251: 
                   1252: sub AUTOLOAD {
                   1253:     our $AUTOLOAD;
                   1254:     return '';
                   1255: }
                   1256: 
1.1       raeburn  1257: 1;

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