help logoLON-CAPA Help

Course requests for official courses, i.e., courses with a valid institutional code, can be set to be processed automatically, on submission, if the requestor has been validated as the instructor of record for the course (based on institutional code).

To provide this functionality the following routines in /home/httpd/lib/pel/ will need to be customized.

validate_instcode(), validate_crsreq(), crsreq_checks().

validate_instcode() is called when a request is being made for an official course. A check is made that the institutional code for which a course is being requested is valid according to the institutional schedule of official classes.

validate_crsreq() is used to check whether a course request should be processed automatically, or held in a queue pending administrative action at the institution.

Course requests will trigger this check if the process type has been set to "validate" for the course type (official, unofficial or community) and the requestor's affiliation. Whether "validate" is an available option in the Domain Configuration menu is controlled by crsreq_checks(). One scenario is where the request is for an official course, in which case a check could be made that the requestor is listed as instructor of record for the course in the institution's course schedule/database. This also involves validate_instcode(), but in this case the username of the course owner is also included, and a more restrictive test is used, namely that the requestor is listed as instructor of record for the course in the institution's course schedule/database.

Other scenarios are possible, and the routine can be customized according to whatever rules a domain wishes to implement to run validations against given the data passed in to the routine.

Customization of possible_instcodes() is also needed to support creation of dropdown lists used by the requestor when selecting the institutional code for the course to be created.


Two arguments are always required, and a third is needed if instructor of record status is being checked.

  1. LON-CAPA domain that will contain the course

  2. institutional code (in the MSU case this is a concatenation of semester code, department code, and course number, e.g., fs03nop590).

  3. optional institutional username for the course owner.

An array is returned containing:

  1. the result of the check for a valid instcode.

  2. (optional) course description.

A valid instcode is confirmed by returning 'valid'. Otherwise a description of why the validation check failed can be returned for display to the course requestor. If no course description is available, " should be set as the value of the second item in the returned array.


Six arguments are required:

  1. domain ($dom)

  2. username:domain for the course owner ($owner)

  3. course type - official, unofficial or community ($crstype)

  4. comma-separated list of owner's institutional groups ($inststatuslist)

  5. institutional code ($instcode)

  6. comma-separated list of requested institutional sections ($instseclist)

A valid courserequest is confirmed by returning 'process'. The following can be returned: process, rejected, pending, approval or error (with error condition - no :), followed by a : and then an optional message.

  1. process - the requestor is the recorded instructor - create the course

  2. rejected - the requestor should never be requesting this course, reject the request permanently

  3. pending - the requestor is not the recorded instructor, but could become so after administrative action at the institution. Put the request in a queue and check localenroll:validate_instcode() periodically until the status changes to "valid".

  4. approval - the request will be held pending review by a Domain Coordinator.

  5. error (followed by the error condition).

If the response is pending then the course request is stored in a queue. If your domain is configured to process pending requests for official courses, once validated (see: Help Auto-course creation settings), then the nightly run of will test each currently pending course request, to determine if the owner can now be validated, and if so, will create the course. If the owner remains unvalidated the request will remain in the queue. Domain Coordinators can display a list of requests for official courses, queued pending validation, via the "Course and community creation" page (see: Help Creation Options).


Three arguments are required:

  1. domain for which validation options are needed. ($dom)

  2. ref to array of course types - official, unofficial,community. ($reqtypes)

  3. ref to a hash of a hash which will determine whether "validate" will be one of the possible choices for each course type - outer hash key, and institutional type - inner hash key ($validations).

    For example to allow validate to be a choice for official classes for Faculty, crsreq_checks would include:

    $validations{'official'}{'Faculty'} = 1;

    The institutional types are those defined for the domain in the domain configuration screen for: Default authentication, language, timezone, portal and types (see the Help Defaults help page).

A value of 'ok' should be returned if no errors occurred. The routine used at MSU is as follows:

sub crsreq_checks {

my ($dom,$reqtypes,$validations) = @_;

if ((ref($reqtypes) eq 'ARRAY') && (ref($validations) eq 'HASH')) {

my (%usertypes,@order);

if (&inst_usertypes($dom,\%usertypes,\@order) eq 'ok') {

foreach my $type (@{$reqtypes}) {
foreach my $inst_type (@order) {
if (($type eq 'official') && ($inst_type eq 'Faculty')) {
$validations- > {$type}{$inst_type} = 1;
} else {
$validations- > {$type}$inst_type = ";

return 'ok';



The routine gathers acceptable values for institutional categories to use in the course creation request form for official courses.

Five arguments are required:

  1. domain ($dom)

  2. reference to array of titles ($codetitles), e.g.,
    @{$codetitles} = ('Year','Semester','Department','Number');

  3. reference to hash of abbreviations used in categories ($cat_titles), e.g.,
    %{$$cat_titles{'Semester'}} = (
    fs = > 'Fall',

    ss = > 'Spring',

    us = > 'Summer'


  4. reference to hash of arrays specifying sort order used in category titles ($cat_order), e.g.,
    @{$$cat_order{'Semester'}} = ('ss','us','fs');

  5. reference to array which will contain order of component parts used in institutional code ($code_order), e.g.,
    @{$code_order} = ('Semester','Year','Department','Number');

A value of 'ok' should be returned if no errors occurred.