[LON-CAPA-cvs] cvs: loncom /html/adm/help/tex Institutional_Integration_Course_Requests.tex

[raeburn]

raeburn		Mon May 23 20:34:21 2011 EDT

  Added files:                 
    /loncom/html/adm/help/tex	
                             	Institutional_Integration_Course_Requests.tex 
  Log:
  - Document routines in localenroll.pm which support validation of instructor
    of record status for requestors of official courses, and support immediate
    processing for validated requests, and queuing for unvalidated ones.  
  
  

Index: loncom/html/adm/help/tex/Institutional_Integration_Course_Requests.tex
+++ loncom/html/adm/help/tex/Institutional_Integration_Course_Requests.tex
\label{Institutional_Integration_Course_Requests.tex}
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).

In order to provide this functionality the following routines in /home/httpd/lib/pel/localenroll.pm will need to be customized.

\emph{validate\_instcode()}, \emph{validate\_crsreq()}, \emph{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 \emph{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.

\textbf{\large validate\_instcode}

Two arguments are always required, and a third is needed if instructor of
record status is being checked.
 
\begin{enumerate}
\item LON-CAPA domain that will contain the course
\item institutional code (in the MSU case this is a concatenation of
 semester code, department code, and course number, e.g., fs03nop590).
\item optional institutional username for the course owner.
\end{enumerate}

An array is returned containing:
\begin{enumerate} 
\item the result of the check for a valid instcode.
\item (optional) course description.
\end{enumerate}

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.

\textbf{\large validate\_crsreq}

Six arguments are required:

\begin{enumerate}
\item domain (\$dom)
\item username:domain for the course owner (\$owner)
\item course type -- official, unofficial or community (\$crstype) 
\item comma-separated list of owner's institutional groups (\$inststatuslist)
\item institutional code (\$instcode)
\item comma-separated list of requested institutional sections (\$instseclist)
\end{enumerate}

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.

\begin{enumerate}
\item process  - the requestor is the recorded instructor - create the course
\item rejected - the requestor should never be requesting this course, reject the
                 request permanently
\item 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".
\item approval - the request will be held pending review by a Domain Coordinator.
\item error (followed by the error condition).
\end{enumerate}

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: \ref{Domain_Configuration_Auto_Creation} Auto-course creation settings), then the nightly run of Autocreate.pl 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: \ref{Create_Course} Creation Options). 

\textbf{\large crsreq\_checks}

Three arguments are required:
\begin{enumerate}
\item domain for which validation options are needed. (\$dom)
\item ref to array of course types -- official, unofficial,community. (\$reqtypes)
\item 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:

\begin{quote}
\$validations\{'official'\}\{'Faculty'\} = 1;
\end{quote}

The institutional types are those defined in inst\_usertypes(), and described
in the \ref{Domain_Configuration_Auto_Enrollment} Auto-Enrollment help page.
\end{enumerate}

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

\begin{quotation}
\texttt{sub crsreq\_checks \{}
\begin{quotation}
\texttt{my (\$dom,\$reqtypes,\$validations) = @\_;}

\texttt{if ((ref(\$reqtypes) eq 'ARRAY') \&\& (ref(\$validations) eq 'HASH')) \{}
\begin{quotation}
\texttt{my (\%usertypes,@order);}

\texttt{if (\&inst\_usertypes(\$dom,\textbackslash{}\%usertypes,\textbackslash{}@order) eq 'ok') \{}
\begin{quotation}
\texttt{foreach my \$type (@\{\$reqtypes\}) \{}
\begin{quotation}
\texttt{foreach my \$inst\_type (@order) \{}
\begin{quotation}
\texttt{if ((\$type eq 'official') \&\& (\$inst\_type eq 'Faculty')) \{}
\begin{quotation}
\texttt{\$validations->\{\$type\}\{\$inst\_type\} = 1;}
\end{quotation}
\texttt{\} else \{}
\begin{quotation}
\texttt{\$validations->\{\$type\}{\$inst\_type} = '';}
\end{quotation}
\texttt{\}}
\end{quotation}
\texttt{\}}
\end{quotation}
\texttt{\}}
\end{quotation}
\texttt{\}}
\end{quotation}
\texttt{\}}

\texttt{return 'ok';}
\end{quotation}
\texttt{\}}
\end{quotation}

\textbf{\large possible\_instcodes}

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

Five arguments are required:
\begin{enumerate}
\item domain (\$dom)
\item reference to array of titles (\$codetitles), e.g., 
\begin{quote}
@\{\$codetitles\} = ('Year','Semester',"Department','Number');
\end{quote}
\item reference to hash of abbreviations used in categories (\$cat\_titles), e.g.,
\begin{quote}
\%\{\$\$cat\_titles\{'Semester'\}\} = (
\begin{quote}
fs => 'Fall',

ss => 'Spring',

us => 'Summer'

);
\end{quote}
\end{quote}
\item reference to hash of arrays specifying sort order used in category titles
(\$cat\_order), e.g., 
\begin{quote}
@\{\$\$cat\_order\{'Semester'\}\} = ('ss','us','fs');
\end{quote}
\item reference to array which will contain order of component parts used
in institutional code (\$code\_order), e.g.,
\begin{quote}
@\{\$code\_order\} = ('Semester','Year','Department','Number');
\end{quote}
\end{enumerate}

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