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
/.
    Optionally, the query parameter 'option' contains the name of fields related to classes asked :
    module=adm/raw&ident=&passwd=....&code=abcde&job=listclasses&option=description,supervisor&rclass=

job=getclassesuser list all the classes with connection between the rclass and
/ 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=adm/raw where adm/raw 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.

		Accept the query parameter 'option=hashlogin': 
        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.

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

job=getsheetscores  gets all score from sheet  - JSON only

job=getexamscores   gets all score from exam  - JSON only