Rev 13229 | Rev 14180 | Go to most recent revision | Details | Compare with Previous | Last modification | View Log | RSS feed
Rev | Author | Line No. | Line |
---|---|---|---|
13229 | obado | 1 | # Protocol for WIMS direct connection with other web servers |
23 | reyssat | 2 | |
13229 | obado | 3 | WIMS direct communication with another web server is two-directional. |
4 | It can receive http/https requests from the other server, and/or send http/https requests to the other. |
||
5 | The connectable server must be declared in a file |
||
6 | within the directory `WIMS_HOME/log/classes/.connections/`. |
||
23 | reyssat | 7 | |
13229 | obado | 8 | Requests sent to WIMS should obey the format described below. Results of such requests can be formatted according to the need of the connecting software. |
23 | reyssat | 9 | |
10 | Outgoing requests sent by WIMS can be formatted according to the |
||
13229 | obado | 11 | specification of the receiving software, |
12 | while the result of the request should be formatted according to the need of WIMS, as described below. |
||
23 | reyssat | 13 | |
13229 | obado | 14 | _________________________________________________________________ |
15 | ## Request format |
||
391 | obado | 16 | |
13229 | obado | 17 | A request from a connecting server is an http/https request sent to the main cgi program of the WIMS server, followed by parameter definitions as in a usual http protocol. |
23 | reyssat | 18 | |
13229 | obado | 19 | All requests must contain the following common parameters: |
23 | reyssat | 20 | |
13229 | obado | 21 | --- |
22 | | Name | Value | |
||
23 | |--------|----------------------------| |
||
24 | | module | adm/raw | |
||
25 | | ident | sender identifier (a word, according to the definition in `WIMS_HOME/log/classes/.connections/`) | |
||
26 | | passwd | sender password (as defined in `WIMS_HOME/log/classes/.connections/`) | |
||
27 | | code | a random word. This word will be sent back to the sender, in order to allow it to check whether the result is from the good request. | |
||
28 | | job | type of request, see below. | |
||
23 | reyssat | 29 | |
30 | |||
13362 | obado | 31 | |
13229 | obado | 32 | And the following parameters may be added according to the type |
23 | reyssat | 33 | of the request. |
34 | |||
13229 | obado | 35 | | Name | Value | |
36 | |----------|----------------------------| |
||
37 | | qclass | identifier of the class on the receiving server. It should be an integer. | |
||
38 | | qprogram | | |
||
39 | | quser | user identifier in the receiving server (when the request concerns a particular user). | |
||
40 | | qsheet | sheet identifier in the receiving server (when the request concerns a particular sheet). | |
||
41 | | rclass | identifier of the class on the sending server. | |
||
42 | | format | Format of the data. | |
||
43 | | option | Different meaning according to request. | |
||
44 | | data1 | Different meaning according to request. | |
||
23 | reyssat | 45 | |
13362 | obado | 46 | |
13229 | obado | 47 | For example, the following request checks whether the class `12345` exists on |
48 | the WIMS server `wims.unice.fr`, sent by a connecting server called `friend1` (by |
||
49 | wims.unice.fr), with password `abcde`. |
||
23 | reyssat | 50 | |
13229 | obado | 51 | `https://wims.unice.fr/wims/wims.cgi?module=adm/raw&ident=friend1&passwd=abcde&code=afdqreaf1r783&job=checkclass&qclass=12345&rclass=myclass` |
23 | reyssat | 52 | |
13229 | obado | 53 | Note that for this check to return OK, the class `12345` on wims.unice.fr must |
54 | have declared `friend1/myclass` as connectable. |
||
13362 | obado | 55 | This can be done on an existing class by adding `friend1/myclass` to the `class_connections` parameter in the class `12345` .def file. |
23 | reyssat | 56 | |
9815 | obado | 57 | _______________________________________________________________________________ |
23 | reyssat | 58 | |
13229 | obado | 59 | ## Query output |
23 | reyssat | 60 | |
61 | The query output (that is, the result of the http query) is always of |
||
62 | text/plain type (even if sometimes the output is a binary file). |
||
63 | |||
13229 | obado | 64 | **WIMS OUTPUT TYPE** : (old fashioned way, non-recommended) |
9691 | obado | 65 | The first line of the output content is a status line, which is either a |
66 | word OK followed by the random code contained in the request, or the |
||
67 | word ERROR. If the first line is not as such, then there is a |
||
68 | serious error in the request or a bug in the server software. |
||
69 | In case the status is OK, the remaining of the output content is the |
||
70 | content of the data. Otherwise the second line contains the nature of |
||
71 | the error. |
||
72 | |||
13229 | obado | 73 | **JSON OUTPUT TYPE** : (recommended) |
74 | output values are returned json formatted. (see [http://json.org]() for more |
||
9815 | obado | 75 | details) |
76 | _______________________________________________________________________________ |
||
23 | reyssat | 77 | |
13229 | obado | 78 | ## Types of the requests. |
23 | reyssat | 79 | |
9815 | obado | 80 | A request to WIMS can have the following types (defined by the parameter 'job') |
23 | reyssat | 81 | |
13362 | obado | 82 | ### job=help |
83 | Show this text. |
||
23 | reyssat | 84 | |
13362 | obado | 85 | ### job=checkident |
86 | Check whether the connection is accepted. |
||
23 | reyssat | 87 | |
13362 | obado | 88 | ### job=checkclass |
89 | Check whether the class accepts connection. |
||
23 | reyssat | 90 | |
13362 | obado | 91 | ### job=checkuser |
92 | Check whether the user exists. |
||
23 | reyssat | 93 | |
13362 | obado | 94 | ### job=checksheet |
95 | Check whether the sheet exists. |
||
391 | obado | 96 | |
13362 | obado | 97 | ### job=addclass |
98 | Add a class on the receiving server. |
||
9815 | obado | 99 | |
13362 | obado | 100 | For this request, `data1` should be a multi-line text defining the |
101 | properties of the new class. Each line contains a definition in the format |
||
102 | `name=value`. (This text must be reformatted for http query string) |
||
103 | The following names may be present in the definitions: |
||
23 | reyssat | 104 | |
13362 | obado | 105 | * **mandatory:** |
106 | * description = name of the class |
||
107 | * institution = name of the institution |
||
108 | * supervisor = full name of the supervisor |
||
109 | * email = contact email address |
||
110 | * password = password for user registration |
||
111 | * lang = class language (en, fr, es, it, etc) |
||
112 | * **optional:** |
||
113 | * expiration = class expiration date (yyyymmdd) |
||
114 | (optional, defaults to one year later) |
||
115 | * limit = limit of number of participants |
||
116 | (optional, defaults to 30) |
||
117 | * level = level of the class (optional, defaults to H4) |
||
118 | Valid levels: E1, E2, ..., E6, H1, ..., H6, |
||
119 | U1, ..., U5, G, R |
||
120 | * secure = secure hosts |
||
121 | * bgcolor = page background color |
||
122 | * refcolor = menu background color |
||
123 | * css = css file (must be existing css on the WIMS server) |
||
13229 | obado | 124 | |
13362 | obado | 125 | `data2` should be a multi-line text defining the supervisor account, in the |
126 | same format as for data1. |
||
127 | The following names may be present in the definitions: |
||
23 | reyssat | 128 | |
13362 | obado | 129 | * **mandatory:** |
130 | * lastname = last name of the supervisor user |
||
131 | * firstname = first name of the supervisor user |
||
132 | * password = supervisor user's password, non-crypted. |
||
133 | * **optional** |
||
134 | * email = supervisor email address |
||
135 | * comments = any comments |
||
136 | * regnum = registration number |
||
137 | * photourl = url of a user picture |
||
138 | * participate = list classes (if in a class group) where user participates |
||
139 | * courses = |
||
140 | * classes = |
||
141 | * supervise = |
||
142 | * supervisable = |
||
143 | * external_auth = |
||
144 | * agreecgu = Boolean indicating if user accepted CGU |
||
145 | * regprop[1..5] = custom properties |
||
23 | reyssat | 146 | |
9816 | obado | 147 | |
13362 | obado | 148 | ### job=adduser |
149 | Add a user to the specified class. |
||
23 | reyssat | 150 | |
13362 | obado | 151 | `data1` should be a multi-line text defining the user account. |
152 | The following names may be present in the definitions: |
||
13229 | obado | 153 | |
13362 | obado | 154 | * **mandatory:** |
155 | * lastname = user's lastname |
||
156 | * firstname = user's firstname |
||
157 | * password = user's password, non-crypted. |
||
158 | * **optional** |
||
159 | * email = email address |
||
160 | * comments = any comments |
||
161 | * regnum = registration number |
||
162 | * photourl = url of user’s photo |
||
163 | * participate = list classes where user participates |
||
164 | (only for group and portal) |
||
165 | * courses = special for portal |
||
166 | * classes = special for portal |
||
167 | * supervise = List classes where teacher are administator |
||
168 | (only for group and portal) |
||
169 | * supervisable = `yes/no` ; give right to the user to supervise a class |
||
170 | (only for group and portal) |
||
171 | * external_auth = login for external_auth (by cas or shiboleth for example). |
||
172 | Not useful for Moodle |
||
173 | * agreecgu = if yes, the user will not be asked when he enters |
||
174 | for the first time to agree the cgu |
||
175 | * regprop[1..5] = custom variables, upon to you |
||
176 | (i.e : you can set here an external group for example) |
||
23 | reyssat | 177 | |
178 | |||
13362 | obado | 179 | ### job=modclass |
180 | Modify the properties of a class. |
||
23 | reyssat | 181 | |
13362 | obado | 182 | `data1` should be a multi-line text containing the properties to be redefined. |
183 | Only modified properties need to be present in data1. |
||
23 | reyssat | 184 | |
391 | obado | 185 | |
13362 | obado | 186 | ### job=moduser |
187 | Modify the properties of a user. As modclass. |
||
23 | reyssat | 188 | |
13362 | obado | 189 | ### job=delclass |
190 | Delete a class. |
||
9691 | obado | 191 | |
13362 | obado | 192 | ### job=deluser |
193 | Delete a user. |
||
391 | obado | 194 | |
13362 | obado | 195 | ### job=recuser |
196 | Recover a deleted user. |
||
1373 | bpr | 197 | |
13362 | obado | 198 | ### job=getclass |
199 | Get the properties of a class. |
||
9815 | obado | 200 | |
13362 | obado | 201 | Optionally, the query parameter 'option' may contain the names of fields |
202 | queried. In this case, only the queried properties are returned. |
||
9815 | obado | 203 | |
13362 | obado | 204 | **Note**: definitions for portals have beed added to output variables but are not yet in addclass: |
9815 | obado | 205 | |
13362 | obado | 206 | typename = |
207 | programs = |
||
208 | courses = |
||
209 | classes = |
||
210 | levels = |
||
211 | icourses = |
||
212 | subclasses = |
||
9815 | obado | 213 | |
214 | |||
13362 | obado | 215 | ### job=getsheet |
216 | Get the properties of a sheet (of a class). |
||
9689 | obado | 217 | |
13362 | obado | 218 | Optionally, the query parameter 'option' may contain |
219 | the names of fields queried. In this case, only the |
||
220 | queried properties are returned. |
||
9691 | obado | 221 | |
13362 | obado | 222 | OUTPUT variables: |
9689 | obado | 223 | |
13362 | obado | 224 | queryclass : the requested class |
225 | querysheet : the requested sheet |
||
226 | sheet_properties : list of properties of the requested sheet |
||
227 | (sheet status,expiration date,title,description) |
||
228 | exocnt : number of exercices included |
||
229 | exotitlelist : list of the exercices included (module:params) |
||
9691 | obado | 230 | |
1373 | bpr | 231 | |
13362 | obado | 232 | ### job=listsheets |
233 | List all the sheets of a class. |
||
1373 | bpr | 234 | |
13362 | obado | 235 | OUTPUT variables: |
9815 | obado | 236 | |
13362 | obado | 237 | queryclass : the requested class |
238 | nbsheet : number of sheets in this class |
||
239 | sheettitlelist : list of the sheets with the format "sheet_id:title" |
||
9815 | obado | 240 | |
241 | |||
13362 | obado | 242 | ### job=listclasses |
243 | List all the classes with connection between the `rclass` and `ident/rclass`. |
||
9815 | obado | 244 | |
13362 | obado | 245 | Optionally, the query parameter 'option' contains the name of fields related |
246 | to classes asked: |
||
247 | e.g. : option=description,supervisor |
||
9815 | obado | 248 | |
249 | |||
13362 | obado | 250 | ### job=getclassesuser |
251 | List all the classes with connection between the rclass and `ident/rclass` where the user exists. |
||
9815 | obado | 252 | |
13362 | obado | 253 | Optionally, the query parameter 'option' may contain the names of fields |
254 | queried. In this case, only the queried properties of the classes are |
||
255 | returned. |
||
391 | obado | 256 | |
9815 | obado | 257 | |
13362 | obado | 258 | ### job=getuser |
259 | Get the properties of a user (of a class). |
||
9815 | obado | 260 | |
13362 | obado | 261 | Optionally, the query parameter 'option' may contain the names of fields |
262 | to be queried. In this case, only the queried properties are returned. |
||
263 | The output format is as for 'getclass'. |
||
23 | reyssat | 264 | |
13229 | obado | 265 | |
13362 | obado | 266 | ### job=getcsv |
267 | Get data of the class, under the form of a csv/tsv spreatsheet file. |
||
268 | |||
269 | The query parameter 'format' may be used to specify the desired output format |
||
270 | (csv or tsv, defaults to csv). |
||
271 | The query parameter 'option' should contain a list of desired data columns. |
||
272 | The following names can be included in 'option', with their respective meanings: |
||
273 | |||
274 | * login : user identifiers |
||
275 | * password : user passwords (uncrypted) |
||
276 | * name : user names (last name and first name) |
||
277 | * lastname : user family names |
||
278 | * firstname : user given names |
||
279 | * email : user email addresses |
||
280 | * regnum : user registration numbers |
||
281 | * allscore : all score fields (averages and details) |
||
282 | * averages : score averages (average0, average1, average2) |
||
283 | * average0 : global score average (as computed by WIMS) |
||
284 | * average1 : average of scores automatically attributed by WIMS |
||
285 | * average2 : average of teacher-entered scores |
||
286 | * exams : exam1+exam2+... |
||
287 | * exam1, exam2, ...: scores of each exam |
||
288 | * sheets : sheet1+sheet2+... |
||
289 | * sheet1, sheet2, ...: scores of each worksheet |
||
290 | * manuals : manual1+manual2+... |
||
291 | * manual1, manual2, ...: first, second, ... teacher-entered scores. |
||
292 | |||
9691 | obado | 293 | The output content (below the status line in WIMS format) is a csv/tsv |
9689 | obado | 294 | spreadsheet table. The first row of the table contains |
295 | the names of the fields. The second row gives short |
||
296 | descriptions of each field. The third row is blank. |
||
297 | The rest is the table content, with one row for each user. |
||
23 | reyssat | 298 | |
299 | |||
13362 | obado | 300 | ### job=lightpopup |
301 | Presents an exercise without the top, bottom, and left menu |
||
9815 | obado | 302 | |
13362 | obado | 303 | The syntax is `job=lightpopup&emod=MODULE` where `MODULE` is an exercise module with its parameters. |
13229 | obado | 304 | |
13362 | obado | 305 | option: |
9815 | obado | 306 | |
13362 | obado | 307 | * about : show "about" which gives author information about the exercise (default) |
308 | * noabout : the "about" will not appear. |
||
9691 | obado | 309 | |
13362 | obado | 310 | SAMPLES REQUESTS: |
23 | reyssat | 311 | |
13362 | obado | 312 | * H3/analysis/oeflinf.fr intro in lightpopup mode: |
313 | * [http://127.0.0.1/wims/wims.cgi?module=adm/raw&job=lightpopup&emod=H3%2Fanalysis%2Foeflinf.fr]() |
||
23 | reyssat | 314 | |
13362 | obado | 315 | * "antecedant" exercice from H3/analysis/oeflinf.fr module in lightpopup mode: |
316 | * [http://127.0.0.1/wims/wims.cgi?module=adm/raw&job=lightpopup&emod=H3%2Fanalysis%2Foeflinf.fr&parm=cmd=new;exo=antecedant;qnum=1;qcmlevel=3&option=noabout]() |
||
13229 | obado | 317 | |
23 | reyssat | 318 | |
13362 | obado | 319 | ### job=putcsv |
320 | Put data into the class. |
||
23 | reyssat | 321 | |
13362 | obado | 322 | The data to put is sent as the value of the query parameter `data1`, in the |
323 | same format as for the query `getcsv` above. And with the following |
||
324 | particularities: |
||
325 | Field `login` must be present. |
||
326 | The second row (short descriptions) is not necessary. |
||
327 | WIMS-attributed scores cannot be uploaded, and will be ignored. |
||
328 | If all the necessary fields corresponding to user properties (lastname, |
||
329 | firstname, password, etc.) are present, non-existent users will be |
||
330 | added to the class. This can be used to install the whole user accounts |
||
331 | of the class with one request. |
||
9689 | obado | 332 | |
333 | |||
13362 | obado | 334 | ### job=getlog |
335 | Get the detailed activity registry of a user. |
||
13229 | obado | 336 | |
13362 | obado | 337 | |
338 | ### job=gettime |
||
339 | Get the current time of the server |
||
340 | |||
9815 | obado | 341 | Can be used for synchronization purposes. |
342 | |||
343 | |||
13362 | obado | 344 | ### job=update |
345 | Ask WIMS to update data in a class. |
||
9815 | obado | 346 | |
13362 | obado | 347 | Upon reception of this request, WIMS server will issue queries back to the |
348 | remote server, in order to get the up-to-date information and update the |
||
349 | class. |
||
350 | The query parameter 'option' contains the nature of the update request. |
||
351 | It may be one of the following: |
||
9815 | obado | 352 | |
13229 | obado | 353 | * class : update class properties (corresponding to modclass) |
354 | * user : update properties of a user (moduser) |
||
355 | * scores : teacher-entered scores (putcsv) |
||
9815 | obado | 356 | |
357 | |||
13362 | obado | 358 | ### job=authuser |
359 | Get an authentification for a user. |
||
13229 | obado | 360 | |
13362 | obado | 361 | User's password is not required. |
362 | Accepts the query parameter `option=hashlogin`: |
||
363 | If called with option=hashlogin, `quser` should be the external |
||
364 | identification of user and the function hashlogin is called to convert |
||
365 | such id to a WIMS login. If the user exists in class, it returns a |
||
366 | session number as above. If the user does not exists, the WIMS login is |
||
367 | returned in the error message. |
||
9689 | obado | 368 | |
9691 | obado | 369 | OUTPUT : |
13229 | obado | 370 | |
371 | * wims_session : a session number under which the user can connect |
||
9815 | obado | 372 | with no need of further authentification |
13229 | obado | 373 | * home_url : a complete URL to connect as authentified. |
9691 | obado | 374 | |
5453 | czzmrn | 375 | |
13362 | obado | 376 | ### job=addsheet |
377 | Add a new sheet to the specified class `qclass`. |
||
9815 | obado | 378 | |
13362 | obado | 379 | `data1` may be defined as a multi-line text defining the sheet defs |
380 | The following names may be present in the definitions: |
||
1702 | georgesk | 381 | |
13362 | obado | 382 | **(optional)** |
383 | |||
13229 | obado | 384 | * title = name of the sheet (defaults to "sheet n#") |
385 | * description = description of the sheet (defaults to "sheet n#") |
||
386 | * expiration = expiration date (yyyymmdd) defaults to one year later |
||
387 | * sheetmode = the mode of the sheet: |
||
388 | * 0 : pending (default) |
||
389 | * 1 : active |
||
390 | * 2 : expired |
||
391 | * 3 : expired + hidden |
||
392 | * weight = weight of the sheet in class score |
||
393 | * formula = How the score is calculated for this sheet (0 to 6) |
||
394 | * indicator = what indicator will be used in the score formula (0 to 2) |
||
395 | * contents = the contents for the multi-line file to be created. |
||
396 | The semicolons (;) in this parameter will be |
||
397 | interpreted as new lines. Equal characters (=) must |
||
398 | be replaced by the character AT (@). |
||
399 | There is no check made, so the integrity of the |
||
400 | contents is up to you only! (defaults to "") |
||
23 | reyssat | 401 | |
13362 | obado | 402 | **OUTPUT** : |
391 | obado | 403 | |
13229 | obado | 404 | * queryclass : the requested class |
405 | * sheet_id : id of the new created sheet |
||
4118 | obado | 406 | |
13229 | obado | 407 | |
13362 | obado | 408 | ### job=addexam |
409 | Add a new exam to the specified class `qclass`. |
||
410 | `data1` may be defined as a multi-line text defining the sheet defs, with the same parameters as in addsheet (see above), plus these additional optional parameters: |
||
13229 | obado | 411 | |
13362 | obado | 412 | * duration = exam duration |
413 | * attempts = number of authorized attempts |
||
414 | * cut_hours = Cut hours (format : `yyyymmdd.hh:mm` (separate several hours by spaces). |
||
415 | * opening = Opening Restrictions (IP ranges / Schedules) opening can set a time restriction for recording notes by adding the words > yyyymmdd.hh:mm (start) and/or < yyyymmdd.hh:mm (end). Dates and times must be in server local time and must be separated by spaces. |
||
13229 | obado | 416 | |
417 | |||
13362 | obado | 418 | ### job=addexo |
419 | Add the source file (data1) of an exercise directly to the class, under the name `qexo` |
||
13229 | obado | 420 | |
421 | |||
13362 | obado | 422 | ### job=putexo |
423 | Add content (an existing exercise) to the sheet `qsheet` of the `qclass` class |
||
424 | `data1` may be defined as a multi-line text defining the exo defs, according to these parameters: |
||
13229 | obado | 425 | |
13362 | obado | 426 | * **mandatory** |
427 | * module = the module where comes the erexercice from |
||
428 | * **optional** |
||
429 | * params = list of parameters to add to the module |
||
430 | * points = number of requested points |
||
431 | * weight = Weight of the exercise |
||
432 | * title = title of the exercise in the sheet |
||
433 | * description = description of the exercise in the sheet |
||
13229 | obado | 434 | |
435 | |||
13362 | obado | 436 | ### job=modsheet |
437 | Modify an existing sheet in the specified class. |
||
4118 | obado | 438 | |
13362 | obado | 439 | `data1` may be defined as a multi-line text defining the sheet defs |
440 | (cf addsheet) |
||
9815 | obado | 441 | |
9689 | obado | 442 | |
13362 | obado | 443 | ### job=listexos |
444 | Lists all exercices presents in class `qclass` |
||
9815 | obado | 445 | |
4118 | obado | 446 | |
13362 | obado | 447 | ### job=movexo |
448 | Moves exercice `qexo` from class `qclass` to class `data1` |
||
9815 | obado | 449 | |
13362 | obado | 450 | Condition : Both 2 classes must be linked by `rclass` |
4118 | obado | 451 | |
13362 | obado | 452 | *option*: you can use `copy` to copy file instead of moving it. |
4118 | obado | 453 | |
454 | |||
13362 | obado | 455 | ### job=movexos |
456 | Moves ALL exercice from class `qclass` to class `data1` |
||
4626 | obado | 457 | |
13362 | obado | 458 | Condition: Both 2 classes must be linked by `rclass` |
13229 | obado | 459 | |
13362 | obado | 460 | *option*: you can use `copy` to copy files instead of moving them. |
13229 | obado | 461 | |
4629 | obado | 462 | |
13362 | obado | 463 | ### job=sharecontent |
464 | Declare neighbour classes, allowing class "qclass" to share content with class "data1" |
||
9815 | obado | 465 | |
13362 | obado | 466 | Condition: Both 2 classes must be linked by `rclass` |
9815 | obado | 467 | |
13362 | obado | 468 | The `option` parameter can be used to declare which type of content to share |
469 | (currently, only the "exo" content type is supported) |
||
9815 | obado | 470 | |
471 | |||
13362 | obado | 472 | ### job=linksheet |
473 | Add all exercices from sheet `qsheet` to exam `qexam` |
||
9896 | obado | 474 | |
475 | |||
13362 | obado | 476 | ### job=getscore |
477 | Get all scores from user `quser` (optionaly, you can filter with sheet `qsheet`) |
||
13229 | obado | 478 | |
479 | |||
13362 | obado | 480 | ### job=getsheetscores |
481 | Get all scores from sheet `qsheet` - JSON OUTPUT only |
||
482 | |||
483 | |||
484 | ### job=getexamscores |
||
485 | Get all scores from exam `qexam` - JSON OUTPUT only |
||
486 | |||
487 | |||
13229 | obado | 488 | --- |