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.
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. |
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. This can be done on an existing class by adding friend1/myclass
to the class_connections
parameter in the class 12345
.def file.
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) _______________________________________________________________________________
A request to WIMS can have the following types (defined by the parameter ‘job’)
Show this text.
Check whether the connection is accepted.
Check whether the class accepts connection.
Check whether the user exists.
Check whether the sheet exists.
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:
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:
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:
yes/no
; give right to the user to supervise a class (only for group and portal)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.
Modify the properties of a user. As modclass.
Delete a class.
Delete a user.
Recover a deleted user.
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 =
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)
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"
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
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.
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’.
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.
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:
SAMPLES REQUESTS:
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.
Get the detailed activity registry of a user.
Get the current time of the server
Can be used for synchronization purposes.
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)
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.
Add a new sheet to the specified class `qclass`.
data1
may be defined as a multi-line text defining the sheet defs The following names may be present in the definitions:
(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
Add a new exam to the specified class `qclass`.
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:
yyyymmdd.hh:mm
(separate several hours by spaces).Add the source file (data1) of an exercise directly to the class, under the name `qexo`
Add content (an existing exercise) to the sheet `qsheet` of the `qclass` class
data1
may be defined as a multi-line text defining the exo defs, according to these parameters:
Modify an existing sheet in the specified class.
data1
may be defined as a multi-line text defining the sheet defs (cf addsheet)
Lists all exercices presents in class `qclass`
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.
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.
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)
Add all exercices from sheet `qsheet` to exam `qexam`
Get all scores from user `quser` (optionaly, you can filter with sheet `qsheet`)
Get all scores from sheet `qsheet` - JSON OUTPUT only
Get all scores from exam `qexam` - JSON OUTPUT only