Rev 9967 | Rev 13229 | Go to most recent revision | Blame | Compare with Previous | Last modification | View Log | RSS feed
<pre>
Protocol for WIMS direct connection with other web servers
WIMS direct communication with another web server is two-directional. It can
receive http/https requests from the other server, and/or send http/https
requests to the other. The connectable server must be declared in a file
within the directory WIMS_HOME/log/classes/.connections/.
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.
Outgoing requests sent by WIMS can be formatted according to the
specification of the receiving software, while the result of the request
should be formatted according to the need of WIMS, as described below.
_______________________________________________________________________________
Request format
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.
All requests must contain the following common parameters
---------------------------------------
Name Value
---------------------------------------
module adm/raw
ident sender identifier (a word, according to the definition
in WIMS_HOME/log/classes/.connections/)
passwd sender password (as defined in
WIMS_HOME/log/classes/.connections/)
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.
job type of request, see below.
---------------------------------------------
And the following parameters may be added according to the type
of the request.
---------------------------------------
Name Value
---------------------------------------
qclass identifier of the class on the receiving server.
It should be an integer.
qprogram
quser user identifier in the receiving server (when the request
concerns a particular user).
qsheet sheet identifier in the receiving server (when the request
concerns a particular sheet).
rclass identifier of the class on the sending server.
format Format of the data.
option Different meaning according to request.
data1 Different meaning according to request.
data2 Different meaning according to request.
---------------------------------------------
For example, the following request checks whether the class '12345' exists on
the WIMS server wims.unice.fr, sent by a connecting server called 'friend1' (by
wims.unice.fr), with password 'abcde'.
https://wims.unice.fr/wims/wims.cgi?module=adm/raw&ident=friend1&passwd=abcde&code=afdqreaf1r783&job=checkclass&qclass=12345&rclass=myclass
Note that for this check to return OK, the class '12345' on wims.unice.fr must
have declared friend1/myclass as connectable.
_______________________________________________________________________________
Query output
The query output (that is, the result of the http query) is always of
text/plain type (even if sometimes the output is a binary file).
WIMS OUTPUT TYPE : (old fashioned way, non-recommended)
The first line of the output content is a status line, which is either a
word OK followed by the random code contained in the request, or the
word ERROR. If the first line is not as such, then there is a
serious error in the request or a bug in the server software.
In case the status is OK, the remaining of the output content is the
content of the data. Otherwise the second line contains the nature of
the error.
JSON OUTPUT TYPE : (recommended)
output values are returned json formatted. (see http://json.org for more
details)
_______________________________________________________________________________
Types of the requests.
A request to WIMS can have the following types (defined by the parameter 'job')
job=help Show this text.
job=checkident Check whether the connection is accepted.
job=checkclass Check whether the class accepts connection.
job=checkuser Check whether the user exists.
job=checksheet Check whether the sheet exists.
job=addclass Add a class on the receiving server.
For this request, 'data1' should be a multi-line text defining the
properties of the new class. Each line contains a definition in the format
'name=value'. (This text must be reformatted for http query string)
The following names may be present in the definitions:
(mandatory)
description = name of the class
institution = name of the institution
supervisor = full name of the supervisor
email = contact email address
password = password for user registration
lang = class language (en, fr, es, it, etc)
(optional)
expiration = class expiration date (yyyymmdd)
(optional, defaults to one year later)
limit = limit of number of participants
(optional, defaults to 30)
level = level of the class (optional, defaults to H4)
Valid levels: E1, E2, ..., E6, H1, ..., H6,
U1, ..., U5, G, R
secure = secure hosts
bgcolor = page background color
refcolor = menu background color
css = css file (must be existing css on the WIMS server)
'data2' should be a multi-line text defining the supervisor account, in the
same format as for data1.
The following names may be present in the definitions:
(mandatory)
lastname = last name of the supervisor user
firstname = first name of the supervisor user
password = supervisor user's password, non-crypted.
(optional)
email = supervisor email address
comments = any comments
regnum = registration number
photourl = url of a user picture
participate = list classes (if in a class group) where user participates
courses =
classes =
supervise =
supervisable =
external_auth =
agreecgu = Boolean indicating if user accepted CGU
regprop1, regprop2, ... regprop5 = custom properties
job=adduser Add a user to the specified class.
'data1' should be a multi-line text defining the user account.
The following names may be present in the definitions:
(mandatory)
lastname = user's lastname
firstname = user's firstname
password = user's password, non-crypted.
(optional)
email = email address
comments = any comments
regnum = registration number
photourl = url of user’s photo
participate = list classes where user participates (only for
group and portal)
courses = special for portal
classes = special for portal
supervise = List classes where teacher are administator (only
for group and portal)
supervisable = yes/no ; give right to the user to supervise a
class (only for group and portal)
external_auth = login for external_auth (by cas or shiboleth for
example). Not useful for Moodle
agreecgu = if yes, the user will not be asked when he enters
for the first time to agree the cgu
regprop[1..5] = custom variables, upon to you (i.e : you can set
here an external group for example)
job=modclass Modify the properties of a class.
'data1' should be a multi-line text containing the properties to be redefined.
Only modified properties need to be present in data1.
job=moduser Modify the properties of a user. As modclass.
job=delclass Delete a class.
job=deluser Delete a user.
job=recuser Recover a deleted user.
job=getclass Get the properties of a class.
Optionally, the query parameter 'option' may contain the names of fields
queried. In this case, only the queried properties are returned.
Note: definitions for portals have beed added to output variables but are
not yet in addclass:
typename =
programs =
courses =
classes =
levels =
icourses =
subclasses =
job=getsheet Get the properties of a sheet (of a class).
Optionally, the query parameter 'option' may contain
the names of fields queried. In this case, only the
queried properties are returned.
OUTPUT variables:
queryclass : the requested class
querysheet : the requested sheet
sheet_properties : list of properties of the requested sheet (sheet
status,expiration date,title,description)
exocnt : number of exercices included
exotitlelist : list of the exercices included (module:params)
job=listsheets List all the sheets of a class.
OUTPUT variables:
queryclass : the requested class
nbsheet : number of sheets in this class
sheettitlelist : list of the sheets with the format "sheet_id:title"
job=listclasses List all the classes with connection between the rclass and
$ident/$rclass.
Optionally, the query parameter 'option' contains the name of fields related
to classes asked:
e.g. : option=description,supervisor
job=getclassesuser List all the classes with connection between the rclass and
$ident/$rclass where the user exists.
Optionally, the query parameter 'option' may contain the names of fields
queried. In this case, only the queried properties of the classes are
returned.
job=getuser Get the properties of a user (of a class).
Optionally, the query parameter 'option' may contain the names of fields
to be queried. In this case, only the queried properties are returned.
The output format is as for 'getclass'.
job=getcsv Get data of the class, under the form of a csv/tsv
spreatsheet file.
The query parameter 'format' may be used to specify the desired output format
(csv or tsv, defaults to csv).
The query parameter 'option' should contain a list of desired data columns.
The following names can be included in 'option', with their respective meanings:
login : user identifiers
password : user passwords (uncrypted)
name : user names (last name and first name)
lastname : user family names
firstname : user given names
email : user email addresses
regnum : user registration numbers
allscore : all score fields (averages and details)
averages : score averages (average0, average1, average2)
average0 : global score average (as computed by WIMS)
average1 : average of scores automatically attributed by WIMS
average2 : average of teacher-entered scores
exams : exam1+exam2+...
exam1, exam2, ...:
scores of each exam
sheets : sheet1+sheet2+...
sheet1, sheet2, ...:
scores of each worksheet
manuals : manual1+manual2+...
manual1, manual2, ...:
first, second, ... teacher-entered scores.
The output content (below the status line in WIMS format) is a csv/tsv
spreadsheet table. The first row of the table contains
the names of the fields. The second row gives short
descriptions of each field. The third row is blank.
The rest is the table content, with one row for each user.
job=lightpopup Presents an exercise without the top, bottom, and left menu
The syntax is job=lightpopup&emod=$module where $module is an exercise module
with its parameters.
option:
about : show "about" which gives author information about the
exercise (default)
noabout : the "about" will not appear.
SAMPLES REQUESTS :
* http://127.0.0.1/wims/wims.cgi?module=adm/raw&job=lightpopup&emod=H3%2Fanalysis%2Foeflinf.fr
* 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
job=putcsv Put data into the class.
The data to put is sent as the value of the query parameter 'data1', in the
same format as for the query 'getcsv' above. And with the following
particularities:
Field 'login' must be present.
The second row (short descriptions) is not necessary.
WIMS-attributed scores cannot be uploaded, and will be ignored.
If all the necessary fields corresponding to user properties (lastname,
firstname, password, etc.) are present, non-existent users will be
added to the class. This can be used to install the whole user accounts
of the class with one request.
job=getlog Get the detailed activity registry of a user.
job=gettime Get the current time of the server
Can be used for synchronization purposes.
job=update Ask WIMS to update data in a class.
Upon reception of this request, WIMS server will issue queries back to the
remote server, in order to get the up-to-date information and update the
class.
The query parameter 'option' contains the nature of the update request.
It may be one of the following:
class : update class properties (corresponding to modclass)
user : update properties of a user (moduser)
scores : teacher-entered scores (putcsv)
job=authuser Get an authentification for a user.
User's password is not required.
Accepts the query parameter 'option=hashlogin':
If called with option=hashlogin, quser should be the external
identification of user and the function hashlogin is called to convert
such id to a WIMS login. If the user exists in class, it returns a
session number as above. If the user does not exists, the WIMS login is
returned in the error message.
OUTPUT :
wims_session : a session number under which the user can connect
with no need of further authentification
home_url : a complete URL to connect as authentified.
job=addsheet Add a new sheet to the specified class.
'data1' may be defined as a multi-line text defining the sheet defs
The following names may be present in the definitions:
(mandatory)
(optional)
title = name of the sheet (defaults to "sheet n#")
description = description of the sheet (defaults to "sheet n#")
expiration = expiration date (yyyymmdd) defaults to one year later
sheetmode = the mode of the sheet:
0 : pending (default)
1 : active
2 : expired
3 : expired + hidden
weight = weight of the sheet in class score
formula = How the score is calculated for this sheet (0 to 6)
indicator = what indicator will be used in the score formula (0 to 2)
contents = the contents for the multi-line file to be created.
The semicolons (;) in this parameter will be
interpreted as new lines. Equal characters (=) must
be replaced by the character AT (@).
There is no check made, so the integrity of the
contents is up to you only! (defaults to "")
OUTPUT :
queryclass : the requested class
sheet_id : id of the new created sheet
job=modsheet Modify an existing sheet in the specified class.
'data1' may be defined as a multi-line text defining the sheet defs
(cf addsheet)
job=listexos Lists all exercices presents in class $qclass
job=movexo Moves exercice $qexo from class $qclass to class $data1
Condition : Both 2 classes must be linked by $rclass
# option : you can use "copy" to copy file instead of moving it.
job=movexos Moves ALL exercice from class $qclass to class $data1
Condition: Both 2 classes must be linked by $rclass
# option: you can use "copy" to copy files instead of moving them.
job=sharecontent declare neighbour classes, allowing class "qclass" to share
content with class "data1"
Condition: Both 2 classes must be linked by $rclass
The "option" parameter can be used to declare which type of content to share
(currently, only the "exo" content type is supported)
job=linksheet Add all exercices from sheet $qsheet to exam $qexam
job=getscore Get all scores from user $quser (optionaly, you can filter with sheet $qsheet)
job=getsheetscores Get all scores from sheet $qsheet - JSON OUTPUT only
job=getexamscores Get all scores from exam $qexam - JSON OUTPUT only
</pre>