Subversion Repositories wimsdev

Rev

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
---