Rev 4626 | Blame | 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).
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.
___________________________________________________________________________
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. No output except
the status line.
job=checkclass Check whether the class accepts connection. No output except
the status line.
job=checkuser Check whether the user exists. No output except the status
line.
job=checksheet Check whether the sheet exists. No output except the status
line.
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'. (Of course, this text
must be reformatted for http query string.)
The following names may be present in the definitions:
description = name of the class (mandatory)
institution = name of the institution (mandatory)
supervisor = full name of the supervisor (mandatory)
email = supervisor email address (mandatory)
password = password for user registration (mandatory)
lang = class language (en, fr, es, it, etc) (mandatory)
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 (optional)
bgcolor = page background color
refcolor = menu background color
css = css file (must be existing css on the WIMS server)
Moreover, '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:
lastname (mandatory)
firstname (mandatory)
password = user's password, non-crypted. (mandatory)
email = email address (optional)
comments = any comments (optional)
regnum = registration number (optional)
There is no output data except the status line.
job=adduser Add a user to the specified class. 'data1' should be a
multi-line text defining the user account, with names
as in 'addclass'.
There is no output data except the status line.
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.
There is no output data except the status line.
job=moduser Modify the properties of a user. As modclass.
There is no output data except the status line.
job=delclass Delete a class.
There is no output data except the status line.
job=deluser Delete a user.
There is no output data except the status line.
job=recuser Recover a deleted user.
There is no output data except the status line.
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.
If the output type is WIMS,
it outputs a multi-line text, each line corresponding
to one definition in the format 'name=value', as
for the input format for 'addclass'.
Definitions for portals have beed added (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.
If the output type is WIMS, output is a multi-line text, each line corresponding
to one definition in the format 'name=value', with these names :
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.
If the output type is WIMS, output is a multi-line text, each line corresponding
to one definition in the format 'name=value', with these names :
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 :
module=adm/raw&ident=$ident&passwd=....&code=abcde&job=listclasses&option=description,supervisor&rclass=$rclass
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 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) 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 with query parameter 'emod'.
presents an exercise without the top, bottom, and left menu except for the
"about". The syntax is job=lightpopup&emod=$module where $module is a exercise module
with its parameters.
http://127.0.0.1/wims/wims.cgi?module=adm/raw&job=lightpopup&emod=H3%2Fanalysis%2Foeflinf.fr
option : noabout (the "about" which gives author information about the exercise will not appear).
about (default)
http://127.0.0.1/wims/wims.cgi?module=adm/raw&job=lightpopup&emod=H3%2Fanalysis%2Foeflinf.fr&parm=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.
There is no output data except the status line.
job=getlog Get the detailed activity registry of a user. The
output is in WIMS internal format.
job=gettime Get the current time of the server, can be used for
synchronization purposes.
The output can be formatted according to the desire
of the querying software.
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)
There is no output data except the status line.
job=authuser Get an authentification for a user. The password of
the user is not required.
The output content is either a session number under
which the user can connect with no need of further
authentification (format for WIMS), or 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:
title = name of the sheet (optional, defaults to "sheet n#")
description = description of the sheet (optional, defaults to "sheet n#")
expiration = class expiration date (yyyymmdd) (optional, defaults to one year later)
sheetmode = the mode of the sheet [0 = in preparation, 1 = active, 2 = ?, 3 = expired + hidden] (optional, defaults to 0)
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! (optional, defaults to "")
If the output type is WIMS, output is a multi-line text, each line corresponding
to one definition in the format 'name=value', with these names :
queryclass : the requested class
sheet_id : id of the new created sheet
job=listexos permet de lister tous les exercices presents dans la classe qclass
job=movexo permet de deplacer l'exercice qexo de la classe qclass a la classe data1, a condition que les 2 classes soient liees a rclass
# option peut contenir le mot "copy" pour copier le fichier au lieu de le deplacer.
job=movexos permet de deplacer l'ensemble des exercices de la classe qclass vers la classe data1, a condition que les 2 classes soient liees a rclass
# option peut contenir le mot "copy" pour copier les fichiers au lieu de les deplacer.
job=sharecontent permet de declarer des classes voisines, et de partager des contenus d'une classe "qclass" avec une classe "data1", a condition que les 2 classes soient liees a "rclass"
"option" va contenir le type de contenu à partager. (pour le moment, seul "exo" est pris en compte)
job=linksheet adds all exercices from sheet $qsheet to exam $qexam
job=getsheetscores gets all score from sheet $qsheet - JSON only
job=getexamscores gets all score from exam $qexam - JSON only
</pre>