Annotation of loncom/html/adm/help/tex/Institutional_Integration_Course_Requests.tex, revision 1.7
1.2 raeburn 1: \label{Institutional_Integration_Course_Requests}
1.1 raeburn 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:
1.4 raeburn 7: To provide this functionality the following routines in /home/httpd/lib/pel/localenroll.pm will need to be customized.
1.1 raeburn 8:
1.3 raeburn 9: \emph{validate\_instcode()}, \emph{validate\_crsreq()}, \emph{crsreq\_checks()}.
1.1 raeburn 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:
1.6 raeburn 116: The institutional types are those defined for the domain in the domain configuration
1.7 ! raeburn 117: screen for: Default authentication, language, timezone, portal and types (see the
1.6 raeburn 118: \ref{Domain_Configuration_LangTZAuth} Defaults help page).
1.1 raeburn 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}
1.5 raeburn 140: \texttt{\$validations-$>$\{\$type\}\{\$inst\_type\} = 1;}
1.1 raeburn 141: \end{quotation}
142: \texttt{\} else \{}
143: \begin{quotation}
1.5 raeburn 144: \texttt{\$validations-$>$\{\$type\}{\$inst\_type} = '';}
1.1 raeburn 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}
1.3 raeburn 170: @\{\$codetitles\} = ('Year','Semester','Department','Number');
1.1 raeburn 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}
1.5 raeburn 176: fs =$>$ 'Fall',
1.1 raeburn 177:
1.5 raeburn 178: ss =$>$ 'Spring',
1.1 raeburn 179:
1.5 raeburn 180: us =$>$ 'Summer'
1.1 raeburn 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:
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>