loncom/enrollment/localenroll.pm - view

File: [LON-CAPA] / loncom / enrollment / localenroll.pm
Revision 1.39: download - view: text, annotated - select for diffs
Sun Sep 13 03:14:12 2009 UTC (14 years, 9 months ago) by raeburn
Branches: MAIN
CVS tags: version_2_9_99_0, version_2_9_0, version_2_8_99_1, version_2_8_99_0, bz6209-base, bz6209, PRINT_INCOMPLETE_base, PRINT_INCOMPLETE, HEAD, GCI_3, GCI_2

- &Apache::lonnet::auto_validate_instcode() now returns an array containing:
  - the outcome ('valid' - or some other message) and
  - an (optional) brief description for the course retrieved from
     localenroll::validate_instcode() which likewise returns an array of 2 items.
- Used to set cdescr form element in the course request form for official courses when the instcode has been validated.

1: # functions to glue school database system into Lon-CAPA for 2: # automated enrollment 3: # $Id: localenroll.pm,v 1.39 2009/09/13 03:14:12 raeburn Exp $ 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: # 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: 46: package localenroll; 47: 48: use strict; 49: 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 61: 62: sub run() { 63: my $dom = shift; 64: return 0; 65: } 66: 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> 126: </student> 127: 128: with the following at the top of the file 129: <?xml version="1.0" encoding="UTF-8"?> 130: <!DOCTYPE text> 131: <students> 132: 133: (all comment - s removed) 134: 135: and a closing: 136: </students> 137: 138: The <startdate> and the <enddate> are the activation date and expiration date 139: for this student's role. If they are absent, then the default access start and 140: default access end dates are used. The default access dates can be set when 141: the course is created, and can be modified using the Automated Enrollment 142: Manager, or via the 'Upload a class list','Enroll a single student' or 143: 'Modify student data' utilities in the Enrollment Manager, by checking the 144: 'make these dates the default for future enrollment' checkbox. If no default 145: dates have been set, then the tudent role will be active immediately, and will 146: remain active until the role is explicitly expired using ENRL -> Drop students. 147: If dates are to included in the XML file, they should be in the format 148: YYYY:MM:DD:HH:MM:SS (: separators required). 149: 150: If there were 10 students in fs03nop590001, 5 students in fs03nop59o601, 151: 8 students in fs03nop590602, and 2 students in fs03ost580002, 152: then $$reply{'43551dedcd43febmsul1'} = 25 153: 154: The purpose of the %reply hash is to detect cases where the institutional 155: enrollment is 0 (most likely due to a problem with the data source). 156: In such a case, the LON-CAPA course roster is left unchanged (i.e., no 157: students are expired, even if automated drops is enabled. 158: 159: fetch_enrollment should return a 0 or 1, depending on whether a connection 160: could be established to the institutional data source. 161: 0 is returned if no connection could be made. 162: 1 is returned if connection was successful 163: 164: A return of 1 is required for the calling modules to perform LON-CAPA 165: roster changes based on the contents of the XML classlist file(s), e,g,, 166: msu_43551dedcd43febmsul1_fs03nop590001_classlist.xml 167: 168: XML classlist files are temporary. They are deleted after the enrollment 169: update process in the calling module is complete. 170: 171: 172: =cut 173: 174: sub fetch_enrollment { 175: my ($dom,$affiliatesref,$replyref) = @_; 176: foreach my $crs (sort keys %{$affiliatesref}) { 177: $$replyref{$crs} = 0; 178: } 179: my $okflag = 0; 180: return $okflag; 181: } 182: 183: =pod 184: 185: =item get_sections() 186: 187: This is called by the Automated Enrollment Manager interface 188: (lonpopulate.pm) to create an array of valid sections for 189: a specific institutional coursecode. 190: e.g., for MSU coursecode: fs03nop590 191: ("001","601","602") would be returned 192: 193: If the array returned contains at least one element, then 194: the interface offerred to the course coordinator, lists 195: official sections and provides a checkbox to use to 196: select enrollment in the LON-CAPA course from each official section. 197: 198: get_sections takes two arguments - (a) the institutional coursecode 199: (in the MSU case this is a concatenation of semester code, department 200: and course number), and (b) the LON-CAPA domain that contains the course. 201: 202: If there is no access to official course sections at your institution, 203: then an empty array is returned, and the Automated Enrollment Manager 204: interface will allow the course coordinator to enter section numbers 205: in text boxes. 206: 207: 208: 209: =cut 210: 211: sub get_sections { 212: my ($coursecode,$dom) = @_; 213: my @secs = (); 214: return @secs; 215: } 216: 217: =pod 218: 219: =item new_course() 220: 221: This is called by loncreatecourse.pm and 222: lonpopulate.pm to record that fact that a new course section 223: has been added to LON-CAPA that requires access to institutional data 224: At MSU, this is required, as institutional classlists can only made 225: available to faculty who are officially assigned to a course. 226: 227: The new_course subroutine is used to check that the course owner 228: of the LON-CAPA course is permitted to access the institutional 229: classlist for any course sections and crosslisted classes that 230: the course coordinator wishes to have affiliated with the course. 231: 232: If access is permitted, then 'ok' is returned. 233: The course section or crosslisted course will only be added to the list of 234: affiliates if 'ok' is returned. 235: 236: new_course takes three arguments - 237: (a) the institutional courseID (in the MSU case this is a concatenation of 238: semester code, department code, course number, and section number 239: e.g., fs03nop590001). 240: (b) the course owner. This is the LON-CAPA username and domain of the course 241: coordinator assigned to the course when it is first created, in the form 242: username:domain 243: (c) the LON-CAPA domain that contains the course 244: 245: =cut 246: 247: sub new_course { 248: my ($course_id,$owner,$dom) = @_; 249: my $outcome = 'ok'; 250: return $outcome; 251: } 252: 253: =pod 254: 255: =item validate_courseID() 256: 257: This is called whenever a new course section or crosslisted course 258: is being affiliated with a LON-CAPA course (i.e., by loncreatecourse.pm 259: and the Automated Enrollment Manager in lonpopulate.pm). 260: A check is made that the courseID that the course coordinator wishes 261: to affiliate with the course is valid according to the institutional 262: schedule of official classes 263: 264: A valid courseID is confirmed by returning 'ok' 265: 266: validate_courseID takes two arguments - 267: (a) the institutional courseID (in the MSU case this is a concatenation of 268: semester code, department code, course number, and section number 269: e.g., fs03nop590001). 270: (b) the LON-CAPA domain that contains the course 271: 272: =cut 273: 274: sub validate_courseID { 275: my ($course_id,$dom) = @_; 276: my $outcome = 'ok'; 277: return $outcome; 278: } 279: 280: =pod 281: 282: =item validate_instcode() 283: 284: This is called when a request is being made for an official course. 285: A check is made that the institutional code for which a course is 286: is being requested is valid according to the institutional 287: schedule of official classes. 288: 289: If the username of the course owner is provided, a more restrictive 290: test is used, namely that the requestor is listed as instructor of 291: record for the course in the institution's course schedule/database. 292: 293: validate_instcode takes three arguments - 294: (a) the LON-CAPA domain that will contain the course 295: (b) the institutional code (in the MSU case this is a concatenation of 296: semester code, department code, and course number, e.g., fs03nop590. 297: (c) an optional institutional username for the course owner. 298: 299: An array is returned containing (a) the result of the check for a valid 300: instcode, and (b) an (optional) course description. 301: A valid instcode is confirmed by returning 'valid'. 302: If no course description is available, '' should be set as 303: the value of the second item in the returned array. 304: 305: =cut 306: 307: sub validate_instcode { 308: my ($dom,$instcode,$owner) = @_; 309: my $outcome = ''; 310: my $description = ''; 311: return ($outcome,$description); 312: } 313: 314: =pod 315: 316: =item validate_crsreq() 317: 318: This is used to check whether a course request should be processed 319: automatically, or held in a queue pending administrative action at 320: the institution. 321: 322: Course requests will trigger this check if the process type has been set 323: to 'validate' for the course type (official, unofficial or community) and 324: the requestor's affiliation. Whether "validate" is an available option 325: in the Domain Configuration menu is controlled by auto_courserequest_checks(). 326: One scenario is where the request is for an official course, in which case 327: a check could be made that the requestor is listed as instructor of 328: record for the course in the institution's course schedule/database. 329: 330: Other scenarios are possible, and the routine can be customized according 331: to whatever rules a domain wishes to implement to run validations against 332: given the data passed in to the routine. 333: 334: validate_crsreq takes six arguments - 335: (a) the LON-CAPA domain that will contain the course. 336: (b) the username:domain for the course owner. 337: (c) the course type (official, unofficial or community) 338: (d) a comma-separated list of institutional affiliations of 339: the course owner. 340: (e) the institutional code (in the MSU case this is a concatenation of 341: semester code, department code, and course number, e.g., fs03nop590. 342: (f) a comma-separated list of institutional sections included in 343: the course request (only applicable to official courses). 344: 345: A valid courserequest is confirmed by returning 'process'. 346: The following can be returned: process, rejected, pending, approval or error (with error condition - no :), followed by a : and then an optional message. 347: 348: (a) process - the requestor is the recorded instructor - create the course 349: (b) reject - the requestor should never be requesting this course, reject the 350: request permanently 351: (c) pending - the requestor is not the recorded instructor, but could 352: become so after administrative action at the institution. Put the 353: request in a queue and check localenroll:validate_instcode() 354: periodically until the status changes to "valid". 355: (d) approval - the request will be held pending review by a Domain Coordinator. 356: (e) error (followed by the error condition). 357: 358: =cut 359: 360: sub validate_crsreq { 361: my ($dom,$owner,$crstype,$inststatuslist,$instcode,$instseclist) = @_; 362: my $outcome = 'approval'; 363: return $outcome; 364: } 365: 366: =pod 367: 368: =item crsreq_checks() 369: 370: This is used to determine whether the "validate" option should appear in the 371: possible choices for course request processing in the Domain Configuration 372: menu for Course Requests. Ultimately it is called by domainprefs.pm (via: 373: lonnet -> lond -> localenroll.pm) The domain configuration menu includes 374: a table where columns are course type (official, unofficial or community) 375: and rows are institutional affiliations (e.g., Faculty, Staff, Student etc.). 376: 377: crsreq_checks() takes three arguments: $dom, $reqtyes, $validations. 378: $dom - the domain for which validation options are needed. 379: $reqtypes - ref to an ARRAY of course types (i.e., official, unofficial and community. 380: $validations - ref to a hash of a hash which will determine whether "validate" 381: will be one of the possible choices for each course type (outer hash key), 382: and institutional type (inner hash key). 383: 384: For example to allow validate to be a choice for official classes for Faculty, 385: req_checks would include: 386: 387: $validations{'official'}{'Faculty'} = 1; 388: 389: This routine is closely tied to validate_crsreq(). "Validate" should not be 390: a possible choice in the domain configuration menu for a particular course 391: type/institutional affiliation, unless a corresponding validation code has 392: been implemented in validate_crsreq(). 393: 394: For example at MSU, official courses requested by Faculty will be validated 395: against the official schedule of classes to check that the requestor is one 396: of the instructors of record for the course. In this case validate_crsreq() 397: includes a call to validate_instcode(). 398: 399: =cut 400: 401: sub crsreq_checks { 402: my ($dom,$reqtypes,$validations) = @_; 403: if ((ref($reqtypes) eq 'ARRAY') && (ref($validations) eq 'HASH')) { 404: my (%usertypes,@order); 405: if (&inst_usertypes($dom,\%usertypes,\@order) eq 'ok') { 406: foreach my $type (@{$reqtypes}) { 407: foreach my $inst_type (@order) { 408: $validations->{$type}{$inst_type} = 0; 409: } 410: } 411: } 412: } 413: return 'ok'; 414: } 415: 416: =pod 417: 418: =item create_password() 419: 420: This is called when the authentication method set for the automated 421: enrollment process when enrolling new users in the domain is "localauth". 422: This could be signalled for the specific user by the value of localauth 423: for the <authtype> tag from the classlist.xml files, or if this is blank, 424: the default authtype, set by the domain coordinator when creating the course 425: with loncreatecourse.pm. 426: 427: create_password takes three arguments - 428: (a) $authparam - the value of <autharg> from the classlist.xml files, 429: or if this blank, the default autharg, set by the domain coordinator when 430: creating the course with loncreatecourse.pm 431: (b) $dom - the domain of the new user. 432: (c) $username - the username of the new user (currently not actually used) 433: 434: Four values are returned: 435: (a) the value of $authparam - which might have been changed 436: (b) a flag to indicate whether a password had been created 437: 0 means no password created 438: 1 means password created. In this case the calling module - Enrollment.pm 439: will send the LON-CAPA username and password to the new user's e-mail 440: (if one was provided), or to the course owner (if one was not provided and 441: the new user was created by the automated process), or to the active 442: course coordinator (if the new user was created using the 'update roster 443: now' interface included in the Automated Enrollment Manager). 444: (c) a flag to indicate that the authentication method is correct - 'ok'. 445: If $authchk is not set to 'ok' then account creation and enrollment of the 446: new user will not occur. 447: (d) if a password was created it can be sent along. This is the password 448: which will be included in the e-mail sent to the new user, or made available 449: to the course owner/course coordinator if no e-mail address is provided. If 450: you do not wish to send a password, but want to give instructions on obtaining 451: one, you could set $newpasswd as those instructions. (e.g., 452: $newpasswd = '(Please visit room 212, ACNS Bldg. to obtain your password)'; 453: The value of $newpasswd is NOT written in the user's LON-CAPA passwd file in 454: /home/httpd/lonUsers/$dom/a/b/c/abcuser/passwd, which in the case of a user 455: employing localauth will contain 'localauth:$authparam'. If you need to include 456: a parameter in the user's passwd file, you should return it as $authparam, 457: i.e., the first of the variables returned by create_password(). 458: 459: 460: =cut 461: 462: sub create_password { 463: my ($authparam,$dom,$username) = @_; 464: my $authchk = 'ok'; 465: my $newpasswd = ''; 466: my $create_passwd = 0; 467: return ($authparam,$create_passwd,$authchk,$newpasswd); 468: } 469: 470: =pod 471: 472: =item instcode_format() 473: 474: Split coursecodes into constituent parts. 475: e.g., INSTITUTIONALCODE = fs03nop590, LON-CAPA COURSEID: 43551dedcd43febmsul1 476: (MSU's course naming scheme - fs03 = Fall semester 2003, nop = 477: department name, 590 = course number) 478: 479: Incoming data: 480: $dom (domain) 481: $$instcodes{'43551dedcd43febmsul1'} = 'fs03nop590' (hash of courseIDs) 482: 483: fs03nop590 would be split as follows 484: @{$codetitles} = ("year","semester","department","number") 485: $$codes{'year'} = '2003' 486: $$codes{'semester'} = 'Fall' 487: $$codes{'department'} = 'nop' 488: $$codes{'number'} = '590' 489: 490: requires six arguments: 491: domain ($dom) 492: reference to hash of institutional course IDs ($instcodes) 493: reference to hash of codes ($codes) 494: reference to array of titles ($codetitles) 495: reference to hash of abbreviations used in categories 496: reference to hash of arrays specifying sort order used in category titles 497: 498: e.g., %{$$cat_titles{'Semester'}} = ( 499: fs => 'Fall', 500: ss => 'Spring', 501: us => 'Summer'); 502: 503: e.g., @{$$cat_order{'Semester'}} = ('ss','us','fs'); 504: returns 1 parameter: 'ok' if no processing errors. 505: 506: Detailed help: 507: http://yourloncapaserver/adm/help/Institutional_Integration_Course_Codes.hlp 508: 509: =cut 510: 511: 512: sub instcode_format () { 513: my ($dom,$instcodes,$codes,$codetitles,$cat_titles,$cat_order) = @_; 514: my $outcome = 'ok'; 515: return $outcome; 516: } 517: 518: =pod 519: 520: =item possible_instcodes() 521: 522: Gather acceptable values for institutional categories to use in course creation request form for official courses. 523: 524: requires four arguments: 525: domain ($dom) 526: reference to array of titles ($codetitles) 527: reference to hash of abbreviations used in categories ($cat_titles). 528: reference to hash of arrays specifying sort order used in category titles ($cat_order). 529: 530: e.g., 531: @{$codetitles} = ("Year","Semester","Department","Number"); 532: 533: %{$$cat_titles{'Semester'}} = ( 534: fs => 'Fall', 535: ss => 'Spring', 536: us => 'Summer'); 537: 538: @{$$cat_order{'Semester'}} = ('ss','us','fs'); 539: 540: returns 1 parameter: 'ok' if no processing errors. 541: 542: =cut 543: 544: sub possible_instcodes { 545: my ($dom,$codetitles,$cat_titles,$cat_order) = @_; 546: @{$codetitles} = (); 547: %{$$cat_titles{'Semester'}} = (); 548: @{$$cat_order{'Semester'}} = ('ss','us','fs'); 549: ($$cat_titles{'Department'},$$cat_order{'Department'}) = &get_all_depts($dom); 550: ($$cat_titles{'Year'},$$cat_order{'Year'}) = &get_possible_years($dom); 551: return 'ok'; 552: } 553: 554: 555: 556: =pod 557: 558: =item institutional_photos() 559: 560: Called when automated enrollment manager is used to update student photos. 561: 562: Incoming data: six arguments 563: (a) $dom (domain) 564: (b) $crs (LONCAPA course number) 565: (c) $affiliates: a reference to a hash with the keys set to the 566: institutional course IDs for the course. 567: (d) $result: a reference to a hash which will return usernames 568: of students (& separated) in following categories (the keys): 569: new, update, missing, same, deleted, noid, nouser. The list 570: includes those students for whom the result of the modification 571: process was either addition of a new photo. update of an 572: existing photo, photo was found to be missing from institution's 573: data store, photo used is same as before, or photo was 574: deleted from storage on LON-CAPA server housing student's 575: information, no student/employee ID was available. 576: 577: (e) $action: the type of action needed. (e.g., update, delete); 578: (f) $students: a reference to a hash with the keys set to student 579: usernames and domains in the form username:domain, and values set 580: to the studentID, if action is required for specific students. 581: 582: returns 1 parameter: 'ok' if no processing errors. 583: other course or student specific values can be stored as values 584: in the appropriate referenced hashes. 585: 586: =cut 587: 588: sub institutional_photos { 589: my ($dom,$crs,$affiliates,$result,$action,$students) = @_; 590: my $outcome = 'ok'; 591: return $outcome; 592: } 593: 594: =pod 595: 596: =item photo_permission() 597: 598: Incoming data: three arguments 599: (a) $dom (domain) 600: (b) $perm_reqd: a reference to a a scalar that is either 'yes' 601: if a course owner must indicate acceptance of conditions of use, 602: 'no' otherwise. 603: (c) $conditions: the text of the conditions of use. 604: 605: returns 1 parameter: 'ok' if no processing errors. 606: $$perm_reqd is set to 'yes' or 'no' 607: $$agreement is set to conditions of use - plain text string 608: which will be displayed in a textarea in a web form. 609: 610: 611: =cut 612: 613: sub photo_permission { 614: my ($dom,$perm_reqd,$conditions) = @_; 615: $$perm_reqd = 'no'; 616: $$conditions = ''; 617: my $outcome = 'ok'; 618: return $outcome; 619: } 620: 621: =pod 622: 623: =item manager_photo_update() 624: 625: Incoming data: one argument 626: (a) $dom (domain) 627: 628: returns 2 parameters: update (0 or 1), and comment. 629: Called by automated enrollment manager, to determine 630: whether "Update Student photos" button will be available, 631: and if so, the message (plain text string) that will be displayed 632: with the button. 633: 634: 635: =cut 636: 637: sub manager_photo_update { 638: my ($dom) = @_; 639: my $update = 0; 640: my $comment = ''; 641: return ($update,$comment); 642: } 643: 644: =pod 645: 646: 647: =item check_section() 648: 649: Incoming data: three arguments (+ fourth optional argument) 650: (a) $class - institutional class id (coursecode concatanated with section) 651: (b) $owner - course owner (2.2 and later username:domain; pre-2.2 username; 652: 2.6 and later - comma-separated list of 653: username:domain for course owner and co-owners.) 654: (c) $dom - domain of course 655: (d) $dbh - optional database handle 656: 657: returns 1 parameter - $sectioncheck ('ok' or other value). 658: Verifies that at least one of the course owner (or co-owners) have access 659: to classlist for specific class according to institution's SIS 660: 'ok' if access available 661: 662: 663: =cut 664: 665: sub check_section { 666: my ($class,$owner,$dom,$dbh) = @_; 667: my $sectioncheck = 'ok'; 668: return $sectioncheck; 669: } 670: 671: =pod 672: 673: =item instcode_defaults() 674: 675: Incoming data: three arguments 676: (a) $dom - domain 677: (b) $defaults - reference to hash which will contain default regular 678: expression matches for different components of an 679: institutional course code 680: (c) $code_order - reference to array which will contain order of 681: component parts used in institutional code. 682: 683: returns 1 parameter - ('ok' or other value). 684: Used to construct a regular expression to be used when searching for 685: courses based on fragments of an institutional code. 686: $defaults contains defaults to use for each component, and code_order 687: contains keys of hash in order in which they are to be concatenated. 688: 689: e.g., INSTITUTIONALCODE = fs03nop590 690: (MSU's course naming scheme - fs = semester, 03 = year, nop = 691: department name, 590 = course number) 692: 693: %{$defaults} = ( 694: 'Year' => '\d{2}', 695: 'Semester' => '^[sfu]s', 696: 'Department' => '\w{2,3}', 697: 'Number' => '\d{3,4}\w?', 698: ); 699: 700: @{$code_order} = ('Semester','Year','Department','Number'); 701: 702: Detailed help: 703: http://yourloncapaserver/adm/help/Institutional_Integration_Course_Codes.hlp 704: 705: =cut 706: 707: sub instcode_defaults { 708: my ($dom,$defaults,$code_order) = @_; 709: return 'ok'; 710: } 711: 712: 713: =pod 714: 715: =item allusers_info() 716: 717: Incoming data: three arguments 718: (a) $dom - domain 719: (b) $instusers - reference to hash which will contain hashes, 720: where keys will be usernames and value will be a 721: hash of user information. Keys in the inner hash 722: will be some or all of: lastname,firstname, 723: middlename, generation, id, inststatus - 724: institutional status (e.g., faculty,staff,student) 725: Values are all scalars except inststatus, 726: which is an array. 727: (c) $instids - reference to hash which will contain ID numbers. 728: keys will be unique IDs (student or faculty/staff ID) 729: values will be either: scalar (username) or an array 730: if a single ID matches multiple usernames. 731: returns 1 parameter - 'ok' if no processing error, or other value 732: if an error occurred. 733: side effects - populates the $instusers and $instids refs to hashes. 734: with information for all users from all available 735: institutional datafeeds. 736: 737: 738: =cut 739: 740: sub allusers_info { 741: my ($dom,$instusers,$instids) = @_; 742: my $outcome = 'ok'; 743: return $outcome; 744: } 745: 746: =pod 747: 748: =item get_userinfo() 749: 750: Incoming data: four required arguments and additional optional arguments 751: Two modes of operation: 752: (1) Retrieves institutional data for a single user either by username 753: if $uname is included as second argument, or by ID if $id is 754: included as a third argument. Either (b) or (c) must be provided. 755: (g), (h) and (i) will be undefined. 756: (2) Retrieves institutional user data from search of an institutional 757: directory based on a search. (g) and (h) are required. 758: (i) is optional. (b) and (c) will be undefined. 759: 760: (a) $dom - domain 761: (b) $uname - username of user 762: (c) $id - student/faculty ID of user 763: (d) $instusers - reference to hash which will contain info for user 764: as key = value; keys will be one or all of: 765: lastname,firstname,middlename,generation,id,inststatus - 766: institutional status (e.g., faculty,staff,student) 767: Values are all scalars except inststatus, 768: which is an array. 769: (e) $instids - reference to hash which will contain ID numbers - 770: keys will be unique IDs (student or faculty/staff ID) 771: values will be either: scalar (username) or an array 772: if a single ID matches multiple usernames. 773: (f) $types - optional reference to array which contains 774: institutional types to check. 775: (g) $srchby - optional if $uname or $id defined, otherwise required. 776: Allowed values include: 1. lastfirst, 2. last, 3. uname 777: corresponding to searches by 1. lastname,firstname; 778: 2. lastname; 3. username 779: (h) $srchterm - optional if $uname or $id defined, otherwise required 780: String to search for. 781: (i) $srchtype - optional. Allowed values: contains, begins (defaults 782: to exact match otherwise). 783: 784: returns 1 parameter - 'ok' if no processing error, or other value 785: if an error occurred. 786: side effects - populates the $instusers and $instids refs to hashes. 787: with information for specified username, or specified 788: id, if fifth argument provided, from all available, or 789: specified (e.g., faculty only) institutional datafeeds, 790: if sixth argument provided. 791: 792: WARNING: You need to set $outcome to 'ok' once you have customized 793: this routine to communicate with an instititional 794: directory data source, otherwise institutional directory 795: searches will always be reported as being unavailable 796: in domain $dom. 797: 798: =cut 799: 800: sub get_userinfo { 801: my ($dom,$uname,$id,$instusers,$instids,$types, 802: $srchby,$srchterm,$srchtype) = @_; 803: my $outcome = 'unavailable'; 804: return $outcome; 805: } 806: 807: =pod 808: 809: =item inst_usertypes() 810: 811: Incoming data: three arguments 812: (a) $dom - domain 813: (b) $usertypes - reference to hash which will contain 814: key = value, where keys are institution 815: affiliation types (e.g., Faculty, Student etc.) 816: and values are titles (e.g., Faculty/Academic Staff) 817: (c) $order - reference to array which will contain the order in 818: which institutional types should be shown 819: when displaying data tables (e.g., default quotas 820: or updateable user fields (see domainprefs.pm) 821: returns 1 parameter - 'ok' if no processing error, or other value 822: if an error occurred. 823: 824: 825: =cut 826: 827: sub inst_usertypes { 828: my ($dom,$usertypes,$order) = @_; 829: @{$order} = (); 830: %{$usertypes} = (); 831: my $outcome = 'ok'; 832: return $outcome; 833: } 834: 835: =pod 836: 837: =item username_rules() 838: 839: Incoming data: three arguments 840: (a) $dom - domain 841: (b) $ruleshash - reference to hash containing rules 842: (a hash of a hash) 843: keys of top level hash are short names 844: (e.g., netid, noncredit) 845: for each key, value is a hash 846: desc => long name for rule 847: rule => description of rule 848: authtype => (krb5,krb4,int, or loc) 849: authentication type for rule 850: authparm => authentication parameter for rule 851: authparmfixed => 1 if authparm used when 852: creating user for rule must be authparm 853: authmsg => Message to display describing 854: authentication to use for this rule 855: 856: (c) $rulesorder - reference to array containing rule names 857: in order to be displayed 858: 859: 860: returns 'ok' if no processing error. 861: 862: =cut 863: 864: sub username_rules { 865: my ($dom,$ruleshash,$rulesorder) = @_; 866: my $outcome; 867: return $outcome; 868: } 869: 870: =pod 871: 872: =item id_rules() 873: 874: Incoming data: three arguments 875: (a) $dom - domain 876: (b) $ruleshash - reference to hash containing rules 877: (a hash of a hash) 878: keys of top level hash are short names 879: (e.g., netid, noncredit) 880: for each key, value is a hash 881: desc => long name for rule 882: rule => description of rule 883: 884: (c) $rulesorder - reference to array containing rule names 885: in order to be displayed 886: 887: returns 'ok' if no processing error. 888: 889: =cut 890: 891: sub id_rules { 892: my ($dom,$ruleshash,$rulesorder) = @_; 893: my $outcome; 894: return $outcome; 895: } 896: 897: =pod 898: 899: =item selfcreate_rules() 900: 901: Incoming data: three arguments 902: (a) $dom - domain 903: (b) $ruleshash - reference to hash containing rules 904: (a hash of a hash) 905: keys of top level hash are short names 906: (e.g., netid) 907: for each key, value is a hash 908: desc => long name for rule 909: rule => description of rule 910: 911: (c) $rulesorder - reference to array containing rule names 912: in order to be displayed 913: 914: returns 'ok' if no processing error. 915: 916: 917: =cut 918: 919: sub selfcreate_rules { 920: my ($dom,$ruleshash,$rulesorder) = @_; 921: my $outcome; 922: return $outcome; 923: } 924: 925: =pod 926: 927: =item username_check() 928: 929: Incoming data: four arguments 930: (a) $dom - domain (scalar) 931: (b) $uname - username to compare against rules (scalar) 932: (c) $to_check (reference to array of rule names to check) 933: (d) $resultshash (reference to hash of results) 934: hash of results for rule checked 935: - keys are rule names 936: - values are: 1 or 0 (for matched or unmatched) 937: 938: returns 'ok' if no processing error. 939: 940: 941: =cut 942: 943: sub username_check { 944: my ($dom,$uname,$to_check,$resultshash) = @_; 945: my $outcome; 946: return $outcome; 947: } 948: 949: =pod 950: 951: =item id_check() 952: 953: Incoming data: four arguments 954: (a) $dom - domain (scalar) 955: (b) $id - ID to compare against rules (scalar) 956: (c) $to_check (reference to array of rule names to check) 957: (d) $resultshash (reference to hash of results) 958: hash of results for rule checked 959: - keys are rule names 960: - values are: 1 or 0 (for matched or unmatched) 961: 962: returns 'ok' if no processing error. 963: 964: 965: =cut 966: 967: sub id_check { 968: my ($dom,$id,$to_check,$resultshash) = @_; 969: my $outcome; 970: return $outcome; 971: } 972: 973: =pod 974: 975: =item selfcreate_check() 976: 977: Incoming data: four arguments 978: (a) $dom - domain (scalar) 979: (b) $selfcreatename - e-mail proposed as username (compare against rules - scalar) 980: (c) $to_check (reference to array of rule names to check) 981: (d) $resultshash (reference to hash of results) 982: hash of results for rule checked 983: - keys are rule names 984: - values are: 1 or 0 (for matched or unmatched) 985: 986: returns 'ok' if no processing error. 987: 988: 989: =cut 990: 991: sub selfcreate_check { 992: my ($dom,$selfcreatename,$to_check,$resultshash) = @_; 993: my $outcome; 994: return $outcome; 995: } 996: 997: =pod 998: 999: =item AUTOLOAD() 1000: 1001: Incoming data: none 1002: Returns '' 1003: 1004: Prevents errors when undefined subroutines are called in this package 1005: Will allow new routines added in the future to be called from lond etc. 1006: without the need for customized versions of local*.pm packages to be 1007: modified to include the new subroutines immediately. 1008: 1009: See "Programming Perl" 3rd ed. pp 296-298. 1010: 1011: =back 1012: 1013: =cut 1014: 1015: sub AUTOLOAD { 1016: our $AUTOLOAD; 1017: return ''; 1018: } 1019: 1020: 1;