SWAD
social workspace at a distance

SWAD plugins, web service and API documentation

CC BY-SA Antonio Cañas Vargas, 1999-2020

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 informationn 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:


createAccount

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.

loginByUserPasswordKey

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.

loginBySessionKey

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.

getAvailableRoles

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)

getNewPassword

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.

getCourses

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.

getCourseInfo

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.

getGroupTypes

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.

getGroups

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.

sendMyGroups

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.

getDirectoryTree

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:
    • tree: string with the full tree in XML format.
      Example:
      <tree>
      	<dir name="Logos">
      		<file name="prado48x48.gif">
      			<code>103482</code>
      			<size>2026</size>
      			<time>1334483747</time>
      			<license>CC by-nc-sa</license>
      			<publisher>Antonio Cañas Vargas</publisher>
      			<photo>http://openswad.org/swad/photo/nQwJwD6jYd.jpg</photo>
      		</file>
      		<file name="swad48x48.gif">
      			<code>103491</code>
      			<size>1982</size>
      			<time>1334483747</time>
      			<license>CC by-nc-sa</license>
      			<publisher>Antonio Cañas Vargas</publisher>
      			<photo>http://openswad.org/swad/photo/nQwJwD6jYd.jpg</photo>
      		</file>
      	</dir>
      	<file name="Mejoras futuras.pdf">
      		<code>97910</code>
      		<size>224595</size>
      		<time>1334483747</time>
      		<license>CC by-nc-sa</license>
      		<publisher>Antonio Cañas Vargas</publisher>
      		<photo>http://openswad.org/swad/photo/nQwJwD6jYd.jpg</photo>
      	</file>
      </tree>
      						

getFile

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.

getMarks

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.

getTestConfig

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.

getTests

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.

getTrivialQuestion

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.

getGames

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.

getMatches

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.

getMatchStatus

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…).

answerMatchQuestion

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.

getUsers

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.

findUsers

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.

getAttendanceEvents

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.

sendAttendanceEvent

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.

removeAttendanceEvent

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.

getAttendanceUsers

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.

sendAttendanceUsers

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.

getNotifications

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:
        1. documentFile: document. To download the file, clients can call getFile with the value returned in eventCode as parameter fileCode.
        2. teachersFile: teachers' file.
        3. sharedFile: shared file. To download the file, clients can call getFile with the value returned in eventCode as parameter fileCode.
        4. assignment: assignment.
        5. examAnnouncement: exam announcement.
        6. 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.
        7. enrollmentStudent: I have been enroled in a course as a student.
        8. enrollmentTeacher: I have been enroled in a course as a teacher.
        9. enrollmentRequest: enrolment request.
        10. timelineComment: comment to one of my social publishings (posts or comments).
        11. timelineFav: fav to one of my social publishings (posts or comments).
        12. timelineShare: sharing of one of my social posts.
        13. timelineMention: mention to me in a social publishing (post or comment).
        14. follower: a user has followed me.
        15. forumPostCourse: message in a forum of one of my courses.
        16. forumReply: reply to a message in a forum.
        17. notice: notice (yellow note).
        18. message: message to me from another user.
        19. 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.

markNotificationsAsRead

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.

sendNotice

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.

sendMessage

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.

getLocation

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.

sendMyLocation

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.

getLastLocation

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.