Plugins
It is possible to develop plugins for SWAD.
In this context, a plugin
is a program external to SWAD,
that interacts with it to provide some functions not provided by SWAD.
Currently, there is only a plugin available: the SWADroid app
for Android mobile devices,
and other plugins are under development.
SWAD has a form that allows administrators to add new plugins
or edit the existing plugins.
Each plugin is specified by the following elements:
- Code (internal number that identifies the plugin in database).
- Name.
- Description.
- Logo or icon.
- App key.
- URL (optional).
- IP (optional).
Web service
The plugins interact with the program SWAD
through a web service with several operations or functions.
A web service
is a software system that allows the interaction between two computers
connected to Internet.
In our case, SWAD is the server or host that offers the web service,
and the plugin is the client that request one or several functions from the web service.
There are two possible ways to access to a SWAD plugin:
Directly from the external application:
The user logs in directly using a form in the external application.
The external application calls SWAD by using the function
loginByUserPasswordKey.
From SWAD:
The user logs in SWAD.
SWAD provides a listing of the available plugins in the option System > List of plugins.
When the user clicks on the link to a plugin,
the web address resulting of concatenate the URL of that plugin
with the identifier of the current session is used.
For example, if the URL specified in the plugin is http://my.url.com/index.php?mode=session&id=
and the session identifier is cY_kAutNT5HzF3MbflcuXgXFlv00Wmqq9QKeD1aaaRc, the following address is called:
http://my.url.com/index.php?mode=session&id=cY_kAutNT5HzF3MbflcuXgXFlv00Wmqq9QKeD1aaaRc.
The external application then calls SWAD using the function loginBySessionKey.
SOAP
The exchange of information between the SWAD web service (server) and a plugin (client)
is performed through XML (Extensible Markup Language) messages
using the protocol SOAP (Simple Object Access Protocol).
The client sends a SOAP message to the server
with the operation or function that it wants to invoque and a number of parameters.
The server returns an XML document
with the resulting data (users, courses, etc.).
The main core of SWAD, written in C,
uses the tool gSOAP
to implement the SOAP server protocol.
The plugins can be written in any programming language,
so they will use the available libraries in that language to implement the SOAP client protocol.
WSDL
The interface of a web service is given in a format automatically processable written in
WSDL (Web Services Description Language).
The SWAD server provides to the clientes several operations or functions indicated
in the WSDL file:
At the end of the WSDL file you can find the URL to call the SWAD web service.
The CGI executed as answer detects that a call to the web service (and not a normal web request) is performed
if the variable CONTENT_TYPE is set to text/xml.
In this case, it responds to the client with the XML output of the SOAP protocol.
SWAD API (Application Programming Interface): functions provided by SWAD web service
The SWAD web service provides the following functions:
Create a new user account.
- Call parameters:
- userNickname: string starting by @ (@nickname of the user).
- userEmail: string (email of the user).
- userPassword: string, plain password.
- appKey: string, key used by the application.
- Returns a data structure with the following fields:
- userCode: integer, unique identifier of the user.
- If <= 0, an error has happened, the account has not been created.
- -1 → nickname not valid
- -2 → nickname registered by another user
- -3 → e-mail not valid
- -4 → e-mail registered by another user
- -5 → password not valid (too short, too trivial…)
- If > 0, the account has been successfully created
and this unique identifier has been assigned to the new user.
- wsKey: string, identifier used in the calls to other operations.
Use only when userCode > 0.
Returns data of the user, given an identifier of the user (DNI/passport, @nickname or email),
a password and an application key.
- Call parameters:
- userID: string (DNI/passport, @nickname or email of the user).
- userPassword: string, password encrypted with
the algoritthm SHA-512
and in format base64url.
- appKey: string, key used by the application.
- Returns a data structure with the following fields:
- userCode: integer, unique identifier of the user.
- wsKey: string, identifier used in the calls to other operations.
- userNickname: string, user's nickname (without @).
- userID: string, DNI/passport of the user.
- userSurname1: string.
- userSurname2: string.
- userFirstname: string.
- userPhoto: string
with the full URL of a JPG image
of size 150 (width) × 200 (height).
If it is an empty string, the user
has no photo or it can not be shown.
- userBirthday: string, in YYYYMMDD format.
- userRole: integer, maximum role of the user,
with one of the following 4 values:
- 0: unknown, an error has occurred.
- 1: guest, not enroled in any course.
- 2: student in all his/her courses.
- 3: teacher in at least one of his/her courses.
Returns data of the user and course of a session,
given an identifier of session passed to the plugin from SWAD.
- Call parameters:
- sessionID: string passed as parameter to the plugin from SWAD.
- appKey: string, key used by the application.
- Returns a data structure with the following fields:
- userCode: integer, unique identifier of the user.
- degreeCode: integer.
- courseCode: integer.
- wsKey: string, identifier used in the calls to other operations.
- userNickname: string, user's nickname (without @).
- userID: string, DNI/passport of the user.
- userSurname1: string.
- userSurname2: string.
- userFirstname: string.
- userPhoto: string
with the full URL of a JPG image
of size 150 (width) × 200 (height).
If it is an empty string, the user
has no photo or it can not be shown.
- userBirthday: string, in YYYYMMDD format.
- userRole: integer, maximum role of the user,
with one of the following 4 values:
- 0: unknown, an error has occurred.
- 1: guest, not enroled in any course.
- 2: student in all his/her courses.
- 3: teacher in at least one of his/her courses.
- degreeName: string.
- courseName: string.
Get available roles in a course.
- Call parameters:
- Returns a data structure with the following fields:
- roles: integer, with bits set (bit i = 1) on available roles, or clear (bit i = 0) in unavailable roles:
- bit 0: Unknown: User not logged in
- bit 1: Guest: User not belonging to any course
- bit 2: User: Student or teacher outside of her/his courses
- bit 3: Student: Student in the selected course
- bit 4: Non-editing teacher: Teacher in the selected course without permission to edit
- bit 5: Teacher: Teacher in the selected course with permission to edit
- bit 6: Degree admin: Administrator of the degree to which the selected course belongs
- bit 7: Center admin: Administrator of the center to which the selected course belongs
- bit 8: Institution admin: Administrator of the institution to which the selected course belongs
- bit 9: System admin: System administrator (also known as superuser)
Sends a new password by e-mail.
- Call parameters:
- userID: string (DNI/passport, @nickname or email of the user).
- appKey: string, key used by the application.
- Returns a data structure with the following fields:
- success: integer.
If 0 ⇒ error (for example, if the event does not exist).
If not 0 ⇒ success.
Returns the list of courses to which the user belongs.
- Call parameters:
- Returns a data structure with the following fields:
- numCourses: integer, number of courses.
- coursesArray: list of elements,
where each element is a data structure with the following fields:
- courseCode: integer, unique identifier for each course.
- userRole: integer, role of the user in the course,
with one of the following 3 values:
- 0: unknown, an error has occurred.
- 2: student in this course.
- 3: teacher in this course.
- courseShortName: string.
- courseFullName: string.
Returns information about the course.
- Call parameters:
- wsKey: string, identifier returned by
loginByUserPasswordKey or
loginBySessionKey.
- courseCode: integer.
- infoType: string,
with one of the following 7 values:
- introduction: introduction to the course.
- guide: teaching guide of the course.
- lectures: lectures syllabus.
- practicals: practicals (laboratory) syllabus.
- bibliography: bibliography.
- FAQ: FAQ.
- links: links.
- assessment: info on assessment system.
- Returns a data structure with the following fields:
- infoSrc: string,
with one of the following 6 values:
- none: no info. infoTxt will be empty.
- editor: internal editor. infoTxt will contain a full XHTML page.
- plainText: plain text. infoTxt will contain a full XHTML page.
- richText: rich text. infoTxt will contain a full XHTML page.
- page: web page, in HTML format.
infoTxt will contain a full HTML page.
If the page contain images or other archives, the result will be incomplete,
because only the main page is returned.
- URL: URL address. infoTxt will contain the URL in plain text.
- infoTxt: string with the information.
Returns the list of types of group of a course.
Before consulting the list of types of group,
this function opens automatically
the groups of the course that should be open.
- Call parameters:
- Returns a data structure with the following fields:
- numGroupTypes: integer, number of types of group.
- groupTypesArray: list of elements,
where each element is a data structure with the following fields:
- groupTypeCode: integer, identifier of the type of group.
- groupTypeName: string
with the name of the type of group
(for example: "Theory", "Lab").
- mandatory: integer. If not 0 ⇒
the enrolment in group(s) of this type is mandatory
for students of the course,
if there is at least a group of that type open and with vacancies.
- multiple: integer. If not 0 ⇒
the students of the course can enrol
in more than a group of this type.
- openTime: integer of 32 bits with sign,
Unix time.
If 0 ⇒ the teachers have not set a time to open automatically the groups of this type.
If not 0 and it corresponds to a future time ⇒
the groups of this type will be opened
automatically at that time.
Returns the list of all the groups of a course.
Before consulting the list of types of group,
this function opens automatically
the groups of the course that should be open.
- Call parameters:
- Returns a data structure with the following fields:
- numGroups: integer, number of groups.
- groupsArray: list of elements,
where each element is a data structure with the following fields:
- groupCode: integer, unique identifier for each group.
- groupName: string with the name of the group
(for example: "A", "B", "Morning", "Afternoon").
- groupTypeCode: integer, identifier of the type of group to which this group belongs.
- groupTypeName: string with the name of the type of group
(for example: "Theory", "Lab").
- open: integer. If not 0 ⇒ the group is open,
meaning that the students can enrol in or remove from the group.
- maxStudents: integer, maximum number of students in the group.
If < 0 ⇒ there is no limit of students in the group.
- numStudents: integer, current number of students in the group.
- fileZones: integer. If not 0 ⇒ the file zones for this group are enabled.
- member: integer. If not 0 ⇒ the requester belongs to this group.
It sends to the server a list with all the groups in a course
to which the requester wants to belong.
It tries to enrol the user in those groups if possible,
and remove from the groups not in the list.
If all the changes are not possible, no change is performed.
Returns the updated list of all the groups of the course
after the changes performed.
- Call parameters:
- wsKey: string, identifier returned by
loginByUserPasswordKey or
loginBySessionKey.
- courseCode: integer.
- myGroups: string.
List of codes of groups (each code is an integer number)
to which the user wants to belong, separated by commas.
- Returns a data structure with the following fields:
- success: integer.
If 0 ⇒ error (it was impossible to satisfy all the requested changes,
no change performed).
If not 0 ⇒ success (all the requested changes
have been performed).
- numGroups: integer, number of groups.
- groupsArray: list of elements,
with identical format to that of the list groupsArray
returned by the function
getGroups.
Returns the full tree of a file zone (documents, shared files or marks) in a course or a group.
The requester must belong to the course or the group.
- Call parameters:
- wsKey: string, identifier returned by
loginByUserPasswordKey or
loginBySessionKey.
- courseCode: integer.
- groupCode: integer,
if <= 0 ⇒ no group specified,
the zone corresponds to the whole course.
- treeCode: integer,
with one of the following 3 values:
- 1: documents zone.
To download a file,
call
getFile.
- 2: shared files zone.
To download a file,
call
getFile.
- 3: marks zone.
To view marks,
call
getMarks
or getFile:
-
if the requester is a student in the course/group,
the client should call
getMarks
to view the student's specific marks.
-
if the requester is a teacher in the course/group,
the client should call
getFile
to download the HTML file with the marks of several students.
- Returns a data structure with the following fields:
This function must be called each time the user wants to download a file
from a documents zone or a shared files zone in a course or a group.
The requester must belong to the course or group.
The function counts the access as a visit to the file
and returns information about the file.
- Call parameters:
- Returns a data structure with the following fields:
- fileName: string, name of the file.
Example: doc.pdf
- URL: string, full URL for downloading the file.
Example: http://openswad.org/swad/tmp/1ACaVfIj_GT768AqLBxHNKyl9iRW688ntqPW86I8FZU/doc.pdf
- size: integer, size in bytes.
- time: integer of 32 bits with sign, Unix time.
- license: string, license.
Example: "CC by-nc-sa"
- publisherName: string, first name and surnames of the user who uploaded the file.
- publisherPhoto: string with the full URL of a JPG image (of the user who uploaded the file)
with size 150 (width) × 200 (height).
If is a string empty, the user
has no photo or it can not be shown.
Returns information about the marks (qualifications, scores) of the requester
from a given HTML file of marks.
This function is allowed only for students.
The requester must be a student in the course/group.
If the requester is a teacher, the client should call
getFile instead of getMarks.
- Call parameters:
- Returns a data structure with the following fields:
- content: string with a full HTML page containing the marks of the requester.
It's the same content returned in
content
by getNotifications.
Returns the configuration of the tests of a course.
- Call parameters:
- Returns a data structure with the following fields:
- pluggable: integer. If 0 ⇒ the tests can not be downloaded from the client application
and if this calls the function
getTests
it will get an empty list of questions;
if not 0 ⇒ the tests of the course with all the tags visible can be downloaded from the client application
using the function getTests.
- numQuestions: integer, number total of questions of test visible and available for download.
If the course does not allow to export tests (pluggable = 0) ⇒ numQuestions = 0.
If the course has no visible tests questions ⇒ numQuestions = 0.
- minQuestions: integer, minimum number of questions in an exam.
- defQuestions: integer, default number of questions in an exam.
- maxQuestions: integer, maximum number of questions in an exam.
- feedback (obsolete, to be removed in 2021): string with the type of feedback for the user,
with one of the following 5 values:
- nothing: no feedback.
- totalResult: minimum feedback: only total score.
- eachResult: medium feedback: score of each question.
- eachGoodBad: high feedback: correct answer in each question.
- fullFeedback: maximum feedback: text of feedback.
- visibility: integer, with the following meaning for each bit:
- Bit 0 = 1 ⇒ the questions and answers texts are visible in test results.
- Bit 1 = 1 ⇒ the feedback texts are visible in test results.
- Bit 2 = 1 ⇒ which are the correct answers is visible in test results.
- Bit 3 = 1 ⇒ the score of each question is visible in test results.
- Bit 4 = 1 ⇒ the total score of an exam is visible in test results.
Returns the self-assessment tests of a course.
This function should not be callled if the download of tests is not allowed in this course
(if the function getTestConfig returns pluggable = 0).
If in this case you call getTests, the four returned lists devueltas will be empty.
- Call parameters:
- wsKey: string, identifier returned by
loginByUserPasswordKey or
loginBySessionKey.
- courseCode integer.
- beginTime: integer of 32 bits with sign, Unix time.
All the tags not hidden are returned without taking into account beginTime,
but only the questions (and answers) with an edition/change time
later than or equal to beginTime will be returned.
With this parameter, each time the client application requests a test update,
you can send the time of the prior update
(or 0 if it is the first update), minimizing the volume of data to be transferred.
- Returns a data structure with the following fields:
- tagsArray: list of all the tags not hidden,
without having into account beginTime,
where each tag is a data structure with the following fields:
- tagCode: integer, unique identifier for each tag.
- tagText: string.
- questionsArray: list of questions with an edition/change time later than or equal to beginTime,
where each question is a data structure with the following fields:
- questionCode: integer, unique identifier for the question.
- answerType: string,
with one of the following 6 values:
- int: integer number.
- float: floating point number.
- TF: true / false.
- uniqueChoice: choice of a unique answer between several options.
- multipleChoice: choice of several answers between several options.
- text: string.
- shuffle: integer. If not 0 ⇒ the answers can be shuffled.
- stem: string with the stem of the question.
- feedback: string with the feedback of the question.
- answersArray: list of answers of the returned questions,
where each answer is a data structure with the following fields:
- questionCode: integer.
- answerIndex: integer, index or position (0, 1, 2…) of the answer inside the question.
- correct: integer. If not 0 ⇒ the answer is correct.
- answerText: string with the text of the answer.
- answerFeedback: string with the feedback for this answer
(only when answerType is uniqueChoice, multipleChoice or text).
- questionTagsArray: list of tags of the returned questions:
- questionCode: integer.
- tagCode: integer.
- tagIndex: integer, index or position (0, 1, 2…) of the tag inside the question.
Returns a random test question, selected from the "uniqueChoice" questions
in the courses of a given list of degrees,
and with a score in the interval [lowerScore, upperScore].
- Call parameters:
- wsKey: string, identifier returned by loginByUserPasswordKey or loginBySessionKey.
- degrees: string. It can contain one or more degree codes, separated by commas.
- lowerScore: float. lower limit of the question score between -1.0 and 1.0
- upperScore: float. upper limit of the question score between -1.0 and 1.0
- Returns a data structure with the following fields:
- question: data structure with the following fields:
- questionCode: integer, unique identifier for the question, > 0.
If no question found ⇒ a questionCode value <= 0 will be returned.
- answerType: string,
currently only the following value is returned:
- uniqueChoice: choice of a unique answer between several options.
- shuffle: integer. If not 0 ⇒ the answers can be shuffled.
- stem: string with the stem of the question.
- feedback: string with the feedback of the question.
- answersArray: list of answers of the returned question, where each answer is a data structure with the following fields:
- questionCode: integer.
- answerIndex: integer, index or position (0, 1, 2%ellip;) of the answer inside the question.
- correct: integer. If not 0 ⇒ the answer is correct.
- answerText: string with the text of the answer.
- answerFeedback: string with the feedback for this answer.
Returns the list of visible (not hidden) games in a given course.
- Call parameters:
- Returns a data structure with the following fields:
- numGames: integer, number of games.
- gamesArray: list of elements,
where each element is a data structure with the following fields:
- gameCode: integer, unique identifier for each game.
- userSurname1: string.
- userSurname2: string.
- userFirstname: string.
- userPhoto: string
with the full URL of a JPG image
of size 150 (width) × 200 (height).
If it is a string empty, the user
has no photo or it can not be shown.
- startTime: integer of 32 bits with sign, Unix time.
- endTime: integer of 32 bits with sign, Unix time.
- title: string.
- text: string.
- numQuestions: integer, number of questions in game.
- maxGrade: float ≥ 0, maximum grade in game.
- visibility: integer, with the following meaning for each bit:
- Bit 0 = 1 ⇒ the questions and answers texts are visible in match results.
- Bit 1 = 1 ⇒ the feedback texts are visible in match results.
- Bit 2 = 1 ⇒ which are the correct answers is visible in match results.
- Bit 3 = 1 ⇒ the score of each question is visible in match results.
- Bit 4 = 1 ⇒ the total score of the match is visible in match results.
Returns the list of matches in a given game,
associated to the whole course or to the groups to which the requester belongs.
- Call parameters:
- wsKey: string, identifier returned by
loginByUserPasswordKey or
loginBySessionKey.
- courseCode: integer.
- gameCode: integer, identifier of the game.
The code must be a valid value > 0 corresponding to an existing game
returned by
getGames.
The requester must be a student in the course.
- Returns a data structure with the following fields:
- numMatches: integer, number of matches.
- matchesArray: list of elements,
where each element is a data structure with the following fields:
- matchCode: integer, unique identifier for each match.
- userSurname1: string.
- userSurname2: string.
- userFirstname: string.
- userPhoto: string
with the full URL of a JPG image
of size 150 (width) × 200 (height).
If it is a string empty, the user
has no photo or it can not be shown.
- startTime: integer of 32 bits with sign, Unix time.
- endTime: integer of 32 bits with sign, Unix time.
- title: string.
- questionIndex: integer.
- groups: string.
List of codes of groups (each code is an integer number)
to which this match is applicable.
If this list of group codes is empty ⇒
this match is applicable to the whole course.
Get match status to be refreshed in student's screen.
This function should be called:
and the screen should be refreshed according to the status returned.
- Call parameters:
- wsKey: string, identifier returned by
loginByUserPasswordKey or
loginBySessionKey.
- courseCode: integer.
- gameCode: integer, identifier of the game.
The code must be a valid value > 0 corresponding to an existing game
returned by
getGames.
The requester must be a student in the course.
- matchCode: integer, identifier of the match.
The code must be a valid value > 0 corresponding to an existing match
returned by
getMatches.
The requester must be a student in the course, and belong to the groups,
to which this match is associated.
- Returns a data structure with the following fields:
- matchCode: integer, unique identifier of the match.
- If > 0, the teacher's screen is showing the answers and the student has permission to answer.
The caller may draw buttons for the options and call
answerMatchQuestion
if the student either chooses an option or chooses to remove his/her answer.
- If = 0, the match is in a status where the student can not answer
(the match has not started, or has finished, or is in pause, or is showing results).
- If < 0, an error has happened, the requester can not join the match.
- questionIndex: integer
- 0 ⇒ before first question, the match has not started
- 1, 2, 3… ⇒ index of current question
- big number (currently 231 - 1 = 2147483647) ⇒ after last question, the match has finished
- numAnswers: integer, number of options (a, b, c…) in question (only when questionIndex is 1, 2, 3…)
- answerIndex: integer
- If < 0 ⇒ no answer selected.
- If ≥ 0 ⇒ index (0, 1, 2…) of the answer selected (only when questionIndex is 1, 2, 3…).
Send an answer to the current question in a match.
The requester should call this function only if getMatchStatus
has returned matchCode > 0.
After calling this function, the requester should call
getMatchStatus
again in order to get the current status of the match before refreshing the screen.
- Call parameters:
- wsKey: string, identifier returned by
loginByUserPasswordKey or
loginBySessionKey.
- courseCode: integer.
- gameCode: integer, identifier of the game.
The code must be a valid value > 0 corresponding to an existing game
returned by
getGames.
The requester must be a student in the course.
- matchCode: integer, identifier of the match.
- questionIndex: integer, index of question (1, 2, 3…).
- answerIndex: integer.
- If < 0 ⇒ no answer selected.
- If ≥ 0 ⇒ index (0, 1, 2…) of the answer selected.
- Returns a data structure with the following fields:
- matchCode: integer, unique identifier of the match.
- > 0 on success.
- ≤ 0 on error.
Returns the list of users with a given role (students or teachers)
enroled in a course (and optionally in some groups of the course).
- Call parameters:
- wsKey: string, identifier returned by
loginByUserPasswordKey or
loginBySessionKey.
- courseCode: integer
- groups: string.
List of codes of groups (each code is an integer number, all the groups must belong to the course).
If the list is empty, the whole course will be used.
- userRole: integer, role of the users to be listed,
with one of the following 2 values:
- 2: students.
- 3: teachers.
- Returns a data structure with the following fields:
- numUsers: integer, number of users.
- usersArray: list of elements,
where each element is a data structure with the following fields:
- userCode: integer, unique identifier for each user.
- userNickname: string, user's nickname (without @).
- userID: string, DNI/passport of the user.
If the requester is a teacher in the selected course, the ID is shown.
If the requester is a student in the selected course, the ID is hidden.
- userSurname1: string.
- userSurname2: string.
- userFirstname: string.
- userPhoto: string
with the full URL of a JPG image
of size 150 (width) × 200 (height).
If it is an empty string, the user
has no photo or it can not be shown.
Returns a list of users whose full name contains the words given in filter.
- Call parameters:
- wsKey: string, identifier returned by
loginByUserPasswordKey or
loginBySessionKey.
- courseCode: integer
(≤ 0 ⇒ users from the whole platform;
> 0 ⇒ users from the course given by
courseCode).
- filter: string, one or several words separated by spaces.
Only those users whose full name will contain
all the words in filter as substrings will be returned,
provided that the two following conditions are satisfied:
- The length of the longest word in
filter must be ≥ a given n.
Eg. For n = 3, "Bruce Lee" is valid, "B Le" is not valid.
- The total number of characters in all the words
(not counting spaces) must be ≥ a given m.
Eg. For m = 7, "Bruce Lee" is valid, but "Bruce" or "Lee" are not valid.
n and m can change in the server side.
A client should delegate to the server.
If any of these two conditions is not satisfied,
a negative value is returned in numUsers, indicating filter too short.
- userRole: integer, role of the users to be listed,
with one of the following 4 values:
- 0: unknown, any role (guests, students, teachers).
- 1: guests, not enroled in any course.
- 2: students.
- 3: teachers.
- Returns a data structure with the following fields:
- numUsers: integer, number of users found. If < 0 ⇒ filter is too short.
- usersArray: list of elements,
where each element is a data structure with the following fields:
- userCode: integer, unique identifier for each user.
- userNickname: string, user's nickname (without @).
- userID: string, DNI/passport of the user.
If the requester has permission to see the user's ID, the ID is shown.
If not, the ID is hidden.
- userSurname1: string.
- userSurname2: string.
- userFirstname: string.
- userPhoto: string
with the full URL of a JPG image
of size 150 (width) × 200 (height).
If it is an empty string, the user
has no photo or it can not be shown.
Returns the list of the attendance events in a course available for the requester
(associated to the whole course or to the groups to which the requester belongs).
- Call parameters:
- Returns a data structure with the following fields:
- numEvents: integer, number of attendance events.
- eventsArray: list of elements,
where each element is a data structure with the following fields:
- attendanceEventCode: integer, unique identifier for each attendance event.
- hidden: integer. If not 0 ⇒ this attendance event is hidden for students.
- userSurname1: string.
- userSurname2: string.
- userFirstname: string.
- userPhoto: string
with the full URL of a JPG image
of size 150 (width) × 200 (height).
If it is a string empty, the user
has no photo or it can not be shown.
- startTime: integer of 32 bits with sign, Unix time.
- endTime: integer of 32 bits with sign, Unix time.
- commentsTeachersVisible: integer. If not 0 ⇒ the comments made by teachers are visible by the students.
- title: string.
- text: string.
- groups: string.
List of codes of groups (each code is an integer number)
to which this attendance event is applicable.
If this list of group codes is empty ⇒
this attendance event is applicable to the whole course.
Sends an attendance event.
- Call parameters:
- wsKey: string, identifier returned by
loginByUserPasswordKey or
loginBySessionKey.
- attendanceEventCode: integer, unique identifier for each attendance event.
- If <= 0 ⇒ this is a new attendance event.
- If > 0 ⇒ this is an existing attendance event
returned by
getAttendanceEvents.
- courseCode: integer.
The requester must be a teacher in this course.
If
attendanceEventCode > 0 ⇒
courseCode must be the course associated to the attendance event.
- hidden: integer. If not 0 ⇒ this attendance event is hidden for students.
- startTime: integer of 32 bits with sign, Unix time.
- endTime: integer of 32 bits with sign, Unix time.
- commentsTeachersVisible: integer. If not 0 ⇒ the comments made by teachers are visible by the students.
- title: string.
- text: string.
- groups: string.
List of codes of groups (each code is an integer number)
to which this attendance event is applicable.
If this list of group codes is empty ⇒
this attendance event is applicable to the whole course.
- Returns a data structure with the following fields:
- attendanceEventCode: integer, unique identifier of the attendance event.
- > 0 on success.
- ≤ 0 on error.
Removes an existing attendance event.
- Call parameters:
- wsKey: string, identifier returned by
loginByUserPasswordKey or
loginBySessionKey.
- attendanceEventCode: integer, identifier of the attendance event to be removed.
The code must be a valid value > 0 corresponding to an existing attendance event
returned by
getAttendanceEvents.
The requester must be a teacher in the course to which this event is associated.
- Returns a data structure with the following fields:
- attendanceEventCode: integer, unique identifier of the attendance event.
- > 0 on success.
- ≤ 0 on error.
Returns the list of users (students) in an attendance event.
- Call parameters:
- Returns a data structure with the following fields:
- numUsers: integer, number of users.
- usersArray: list of elements,
where each element is a data structure with the following fields:
- userCode: integer, unique identifier for each user.
- userNickname: string, user's nickname (without @).
- userID: string, DNI/passport of the user.
- userSurname1: string.
- userSurname2: string.
- userFirstname: string.
- userPhoto: string
with the full URL of a JPG image
of size 150 (width) × 200 (height).
If it is an empty string, the user
has no photo or it can not be shown.
- present: integer. If not 0 ⇒ this user has attended the event.
Send the list of users (students)
who have attended to an attendance event.
All users in this list will be marked as present;
other users formerly marked as present will be marked as absent when setOthersAsAbsent = 1.
- Call parameters:
- wsKey: string, identifier returned by
loginByUserPasswordKey or
loginBySessionKey.
- attendanceEventCode: integer,
one of the codes returned
by
getAttendanceEvents
or sendAttendanceEvent.
The requester must be a teacher in the course to which this event is associated.
- users: string, list of numbers separated by commas.
Each number is the user's code
(previously returned by
getAttendanceUsers)
of a student who attended this event.
- setOthersAsAbsent: integer:
-
0 ⇒ users from list
users will be added to list of presents
and other users formerly marked as present will not be affected
-
1 ⇒ users from list
users will be marked as present
and other users formerly marked as present will be marked as absent
- Returns a data structure with the following fields:
- success: integer.
If 0 ⇒ error (for example, if the event does not exist).
If not 0 ⇒ success.
- numUsers: integer, number of users found in list and marked as present in the event.
Returns the list of recent notifications for the requester.
- Call parameters:
- wsKey: string, identifier returned by
loginByUserPasswordKey or
loginBySessionKey.
- beginTime: integer of 32 bits with sign, Unix time.
Only the notifications with time later than or equal to this parameter will be shown.
With this parameter, each time the application client requests an update of the notifications,
you can send the time of the former update (or 0 if it is the first update),
minimizing the volume of data to be transferred.
- Returns a data structure with the following fields:
- numNotifications: integer, number of notifications.
- notificationsArray: list of elements,
where each element is a data structure with the following fields:
- notifCode: integer.
Unique identifier for a notification.
When a user opens this notification,
you should call
markNotificationsAsRead with this value.
- eventType: string,
with one of the following 19 values:
- documentFile: document.
To download the file, clients can call
getFile
with the value returned in eventCode
as parameter fileCode.
- teachersFile: teachers' file.
- sharedFile: shared file.
To download the file, clients can call
getFile
with the value returned in eventCode
as parameter fileCode.
- assignment: assignment.
- examAnnouncement: exam announcement.
- marksFile: marks/grades file.
- If the requester is a student,
content
will contain a full HTML page containing the marks of the requester.
The client application can also call getMarks
with the value returned in eventCode
as parameter fileCode.
- If the requester is a teacher,
and he/she wants to download the file,
the client application can call
getFile
with the value returned in eventCode
as parameter fileCode.
- enrollmentStudent: I have been enroled in a course as a student.
- enrollmentTeacher: I have been enroled in a course as a teacher.
- enrollmentRequest: enrolment request.
- timelineComment: comment to one of my social publishings (posts or comments).
- timelineFav: fav to one of my social publishings (posts or comments).
- timelineShare: sharing of one of my social posts.
- timelineMention: mention to me in a social publishing (post or comment).
- follower: a user has followed me.
- forumPostCourse: message in a forum of one of my courses.
- forumReply: reply to a message in a forum.
- notice: notice (yellow note).
- message: message to me from another user.
- survey: survey.
- eventCode: integer.
A non-unique code associated to some notifications.
It corresponds to the code of the document, message, assignment, etc., depending on
eventType.
- eventTime: integer of 32 bits with sign, Unix time.
- userNickname: string, user's nickname (without @).
- userSurname1: string.
- userSurname2: string.
- userFirstname: string.
- userPhoto: string
with the full URL of a JPG image
of size 150 (width) × 200 (height).
If it is a string empty, the user
has no photo or it can not be shown.
- location: string.
- status: integer, with the following meaning for each bit:
- Bit 0 = 1 ⇒ the user wants to receive by email notifications
of this event type.
- Bit 1 = 1 ⇒ the email has been sent.
- Bit 2 = 1 ⇒ the user has read the event
that caused the notification.
- Bit 3 = 1 ⇒ the event
that caused the notification was removed (the notification should be displayed as hidden).
The following combinations are possible:
- X000: No email will be sent, event not read.
- X001: Email pending, event not read.
- X010: (impossible).
- X011: Email sent, event not read.
- X100: No email will be sent, event read.
- X101: Email cancelled because the event has been read before to send it.
- X110: (impossible).
- X111: Email sent, event read.
- summary: string with a brief description of the notification, for example the subject of a message.
- content: string with the full content of the notification, for example the text of a message.
If
eventType is marksFile,
content will be HTML code
with information about the marks (qualifications, scores)
of the logged student from an HTML file of marks.
It marks several notifications as read.
You should call this function when one or more notifications have been open / read by the user.
- Call parameters:
- wsKey: string, identifier returned by
loginByUserPasswordKey or
loginBySessionKey.
- notifications: string.
List of unique notification codes
to be marked as read, separated by commas.
Each code is an integer, a unique identifier of the notification
returned as
notifCode
(not eventCode/notificationCode)
by getNotifications.
- Returns a data structure with the following fields:
- numNotifications: integer, number of notifications found in list and marked as read.
Sends a public notice (yellow note) to a course.
The requester must be a teacher in the course.
- Call parameters:
- Returns a data structure with the following fields:
- noticeCode: integer, unique identifier of the notice, > 0 on success.
On error, this code will be <= 0.
It sends a message to one or more users.
- Call parameters:
- wsKey: string, identifier returned by
loginByUserPasswordKey or
loginBySessionKey.
- messageCode: integer.
- If
messageCode is 0,
this message will be not considered a reply of another message,
and to should contain at least one recipient.
- If
messageCode is not 0,
this message will be considered a reply to a message received in notifications.
In that case it must contain the code returned
by getNotifications in eventCode
(for safety, the server will check that this code of message corresponds really
to a message received previously by the user logged by wsKey).
- to: string.
It can contain one or more IDs, @nicknames or emails of the recipients of the message, separated by commas.
- If
messageCode is 0, to must have at least an ID, @nickname or email.
- If
messageCode is distinct of 0, to can be empty.
- subject: string, subject of the message.
- body: string, body of the message.
- Returns a data structure with the following fields:
- numUsers: integer, number of recipients.
- usersArray: list of elements,
where each element is a data structure, corresponding to a recipient, with the following fields:
- userCode: integer, unique identifier of the recipient.
- userNickname: string, nickname of the recipient (without @).
- userID: string, DNI/passport of the user,
really this function returns a hidden
userID,
so you should not use this field.
- userSurname1: string, first surname of the recipient.
- userSurname2: string, second surname of the recipient.
- userFirstname: string, name of the recipient.
- userPhoto: string
with the full URL of a JPG image
of size 150 (width) × 200 (height).
If it is a string empty, the user
does not have photo or it can not be shown.
Returns a location (institution, center, building and room)
for Wi-Fi-based positioning system given a MAC address.
In order to fill the database that stores the MAC-location pairs,
the client can call function getAvailableRoles
to check if the logged user is allowed to see the MAC address of the nearest Wi-Fi access point.
Only center, institution and system admins should be allowed to see it.
- Call parameters:
- Returns a data structure with the following fields:
- location: a data structure, corresponding to a location, with the following fields:
- institutionCode: integer, unique identifier of the institution.
- institutionShortName: string.
- institutionFullName: string.
- centerCode: integer, unique identifier of the center.
- centerShortName: string.
- centerFullName: string.
- buildingCode: integer, unique identifier of the building.
- buildingShortName: string.
- buildingFullName: string.
- floor: signed integer.
- roomCode: integer, unique identifier of the room
(≤ 0 ⇒ no room found for this MAC;
> 0 ⇒ room found).
- roomShortName: string.
- roomFullName: string.
Sends user's current location (room).
Periodically called from the client to send the user's current location to the server.
- Call parameters:
- Returns a data structure with the following fields:
- success: integer.
If 0 ⇒ error (for example, if the room does not exist).
If not 0 ⇒ success.
Returns the more recent location (institution, center, building and room) of a given user.
A user can only consult the location of another user
if the intersection of the centers of their courses is not empty.
Both users do not have to share any course,
but at least some course of each one has to share center.
- Call parameters:
- Returns a data structure with the following fields:
- location: a data structure, corresponding to a location, with the following fields:
- institutionCode: integer, unique identifier of the institution.
- institutionShortName: string.
- institutionFullName: string.
- centerCode: integer, unique identifier of the center.
- centerShortName: string.
- centerFullName: string.
- buildingCode: integer, unique identifier of the building.
- buildingShortName: string.
- buildingFullName: string.
- floor: signed integer.
- roomCode: integer, unique identifier of the room
(≤ 0 ⇒ the user has no registered her/his last location, or you don't have permission to see it;
> 0 ⇒ room found).
- roomShortName: string.
- roomFullName: string.
- checkinTime: integer of 32 bits with sign, Unix time.
|
Antonio Cañas Vargas, 1999-2021