Return to Institutional_Integration_Course_Requests.tex CVS log

Up to [LON-CAPA] / loncom / html / adm / help / tex

- Documentation. Replace a long string with a list which can be split across
  two lines in the PDF.

    1: \label{Institutional_Integration_Course_Requests}
    2: Course requests for official courses, i.e., courses with a valid
    3: institutional code, can be set to be processed automatically, on submission,
    4: if the requestor has been validated as the instructor of record for the
    5: course (based on institutional code).
    6: 
    7: To provide this functionality the following routines in /home/httpd/lib/pel/localenroll.pm will need to be customized.
    8: 
    9: \emph{validate\_instcode()}, \emph{validate\_crsreq()}, \emph{crsreq\_checks()}.
   10: 
   11: validate\_instcode() is called when a request is being made for an official course.
   12: A check is made that the institutional code for which a course is being 
   13: requested is valid according to the institutional schedule of official classes.
   14:  
   15: validate\_crsreq() is used to check whether a course request should be 
   16: processed automatically, or held in a queue pending administrative
   17: action at the institution.
   18: 
   19: Course requests will trigger this check if the process type has been set
   20: to ``validate'' for the course type (official, unofficial or community) and
   21: the requestor's affiliation.  Whether ``validate'' is an available option
   22: in the Domain Configuration menu is controlled by crsreq\_checks().
   23: One scenario is where the request is for an official course, in which case
   24: a check could be made that the requestor is listed as instructor of
   25: record for the course in the institution's course schedule/database.
   26: This also involves validate\_instcode(), but in this case the username 
   27: of the course owner is also included, and a more restrictive
   28: test is used, namely that the requestor is listed as instructor of
   29: record for the course in the institution's course schedule/database.
   30: 
   31: Other scenarios are possible, and the routine can be customized according
   32: to whatever rules a domain wishes to implement to run validations against
   33: given the data passed in to the routine.
   34:  
   35: Customization of \emph{possible\_instcodes()} is also needed to support creation
   36: of dropdown lists used by the requestor when selecting the institutional code
   37: for the course to be created.
   38: 
   39: \textbf{\large validate\_instcode}
   40: 
   41: Two arguments are always required, and a third is needed if instructor of
   42: record status is being checked.
   43:  
   44: \begin{enumerate}
   45: \item LON-CAPA domain that will contain the course
   46: \item institutional code (in the MSU case this is a concatenation of
   47:  semester code, department code, and course number, e.g., fs03nop590).
   48: \item optional institutional username for the course owner.
   49: \end{enumerate}
   50: 
   51: An array is returned containing:
   52: \begin{enumerate} 
   53: \item the result of the check for a valid instcode.
   54: \item (optional) course description.
   55: \end{enumerate}
   56: 
   57: A valid instcode is confirmed by returning 'valid'. 
   58: Otherwise a description of why the validation check failed can be returned
   59: for display to the course requestor.
   60: If no course description is available, '' should be set as
   61: the value of the second item in the returned array.
   62: 
   63: \textbf{\large validate\_crsreq}
   64: 
   65: Six arguments are required:
   66: 
   67: \begin{enumerate}
   68: \item domain (\$dom)
   69: \item username:domain for the course owner (\$owner)
   70: \item course type -- official, unofficial or community (\$crstype) 
   71: \item comma-separated list of owner's institutional groups (\$inststatuslist)
   72: \item institutional code (\$instcode)
   73: \item comma-separated list of requested institutional sections (\$instseclist)
   74: \end{enumerate}
   75: 
   76: A valid courserequest is confirmed by returning 'process'.
   77: The following can be returned: process, rejected, pending, approval or error 
   78: (with error condition - no :), followed by a : and then an optional message.
   79: 
   80: \begin{enumerate}
   81: \item process  - the requestor is the recorded instructor - create the course
   82: \item rejected - the requestor should never be requesting this course, reject the
   83:                  request permanently
   84: \item pending - the requestor is not the recorded instructor, but could
   85:       become so after administrative action at the institution. Put the
   86:       request in a queue and check localenroll:validate\_instcode()
   87:       periodically until the status changes to "valid".
   88: \item approval - the request will be held pending review by a Domain Coordinator.
   89: \item error (followed by the error condition).
   90: \end{enumerate}
   91: 
   92: If the response is pending then the course request is stored in a queue. 
   93: If your domain is configured to process pending requests for official courses,
   94: once validated (see: \ref{Domain_Configuration_Auto_Creation} Auto-course creation settings), then the nightly run of Autocreate.pl will test each currently
   95: pending course request, to determine if the owner can now be validated, 
   96: and if so, will create the course.
   97: 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: \ref{Create_Course} Creation Options). 
   98: 
   99: \textbf{\large crsreq\_checks}
  100: 
  101: Three arguments are required:
  102: \begin{enumerate}
  103: \item domain for which validation options are needed. (\$dom)
  104: \item ref to array of course types -- official, unofficial,community. (\$reqtypes)
  105: \item ref to a hash of a hash which will determine whether ``validate''
  106: will be one of the possible choices for each course type - outer hash key,
  107: and institutional type - inner hash key (\$validations).
  108: 
  109: For example to allow validate to be a choice for official classes for Faculty,
  110: crsreq\_checks would include:
  111: 
  112: \begin{quote}
  113: \$validations\{'official'\}\{'Faculty'\} = 1;
  114: \end{quote}
  115: 
  116: The institutional types are those defined for the domain in the domain configuration
  117: screen for: Default authentication, language, timezone, portal and types (see the 
  118: \ref{Domain_Configuration_LangTZAuth} Defaults help page).
  119: \end{enumerate}
  120: 
  121: A value of 'ok' should be returned if no errors occurred.
  122: The routine used at MSU is as follows:
  123: 
  124: \texttt{sub crsreq\_checks \{}
  125: \begin{quotation}
  126: \texttt{my (\$dom,\$reqtypes,\$validations) = @\_;}
  127: 
  128: \texttt{if ((ref(\$reqtypes) eq 'ARRAY') \&\& (ref(\$validations) eq 'HASH')) \{}
  129: \begin{quotation}
  130: \texttt{my (\%usertypes,@order);}
  131: 
  132: \texttt{if (\&inst\_usertypes(\$dom,\textbackslash{}\%usertypes,\textbackslash{}@order) eq 'ok') \{}
  133: \begin{quotation}
  134: \texttt{foreach my \$type (@\{\$reqtypes\}) \{}
  135: \begin{quotation}
  136: \texttt{foreach my \$inst\_type (@order) \{}
  137: \begin{quotation}
  138: \texttt{if ((\$type eq 'official') \&\& (\$inst\_type eq 'Faculty')) \{}
  139: \begin{quotation}
  140: \texttt{\$validations-$>$\{\$type\}\{\$inst\_type\} = 1;}
  141: \end{quotation}
  142: \texttt{\} else \{}
  143: \begin{quotation}
  144: \texttt{\$validations-$>$\{\$type\}{\$inst\_type} = '';}
  145: \end{quotation}
  146: \texttt{\}}
  147: \end{quotation}
  148: \texttt{\}}
  149: \end{quotation}
  150: \texttt{\}}
  151: \end{quotation}
  152: \texttt{\}}
  153: \end{quotation}
  154: \texttt{\}}
  155: 
  156: \texttt{return 'ok';}
  157: \end{quotation}
  158: \texttt{\}}
  159: 
  160: \textbf{\large possible\_instcodes}
  161: 
  162: The routine gathers acceptable values for institutional categories to use 
  163: in the course creation request form for official courses.
  164: 
  165: Five arguments are required:
  166: \begin{enumerate}
  167: \item domain (\$dom)
  168: \item reference to array of titles (\$codetitles), e.g., 
  169: \begin{quote}
  170: @\{\$codetitles\} = ('Year','Semester','Department','Number');
  171: \end{quote}
  172: \item reference to hash of abbreviations used in categories (\$cat\_titles), e.g.,
  173: \begin{quote}
  174: \%\{\$\$cat\_titles\{'Semester'\}\} = (
  175: \begin{quote}
  176: fs =$>$ 'Fall',
  177: 
  178: ss =$>$ 'Spring',
  179: 
  180: us =$>$ 'Summer'
  181: 
  182: );
  183: \end{quote}
  184: \end{quote}
  185: \item reference to hash of arrays specifying sort order used in category titles
  186: (\$cat\_order), e.g., 
  187: \begin{quote}
  188: @\{\$\$cat\_order\{'Semester'\}\} = ('ss','us','fs');
  189: \end{quote}
  190: \item reference to array which will contain order of component parts used
  191: in institutional code (\$code\_order), e.g.,
  192: \begin{quote}
  193: @\{\$code\_order\} = ('Semester','Year','Department','Number');
  194: \end{quote}
  195: \end{enumerate}
  196: 
  197: A value of 'ok' should be returned if no errors occurred.
  198: