Annotation of loncom/html/adm/help/tex/Institutional_Integration_Course_Requests.tex, revision 1.1
1.1 ! raeburn 1: \label{Institutional_Integration_Course_Requests.tex}
! 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: In order 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 in inst\_usertypes(), and described
! 117: in the \ref{Domain_Configuration_Auto_Enrollment} Auto-Enrollment help page.
! 118: \end{enumerate}
! 119:
! 120: A value of 'ok' should be returned if no errors occurred.
! 121: The routine used at MSU is as follows:
! 122:
! 123: \begin{quotation}
! 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: \end{quotation}
! 160:
! 161: \textbf{\large possible\_instcodes}
! 162:
! 163: The routine gathers acceptable values for institutional categories to use
! 164: in the course creation request form for official courses.
! 165:
! 166: Five arguments are required:
! 167: \begin{enumerate}
! 168: \item domain (\$dom)
! 169: \item reference to array of titles (\$codetitles), e.g.,
! 170: \begin{quote}
! 171: @\{\$codetitles\} = ('Year','Semester',"Department','Number');
! 172: \end{quote}
! 173: \item reference to hash of abbreviations used in categories (\$cat\_titles), e.g.,
! 174: \begin{quote}
! 175: \%\{\$\$cat\_titles\{'Semester'\}\} = (
! 176: \begin{quote}
! 177: fs => 'Fall',
! 178:
! 179: ss => 'Spring',
! 180:
! 181: us => 'Summer'
! 182:
! 183: );
! 184: \end{quote}
! 185: \end{quote}
! 186: \item reference to hash of arrays specifying sort order used in category titles
! 187: (\$cat\_order), e.g.,
! 188: \begin{quote}
! 189: @\{\$\$cat\_order\{'Semester'\}\} = ('ss','us','fs');
! 190: \end{quote}
! 191: \item reference to array which will contain order of component parts used
! 192: in institutional code (\$code\_order), e.g.,
! 193: \begin{quote}
! 194: @\{\$code\_order\} = ('Semester','Year','Department','Number');
! 195: \end{quote}
! 196: \end{enumerate}
! 197:
! 198: A value of 'ok' should be returned if no errors occurred.
! 199:
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>