social workspace at a distance

# SWAD plugins, web service and API documentation

Antonio Cañas Vargas, 1999-2018

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

- http://openswad.org/api/swad.wsdl
- http://swad.ugr.es/ws/swad.wsdl

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`
- `loginByUserPasswordKey`
- `loginBySessionKey`
- `getNewPassword`
- `getCourses`
- `getCourseInfo`
- `getGroupTypes`
- `getGroups`
- `sendMyGroups`
- `getDirectoryTree`
- `getFile`
- `getMarks`
- `getTestConfig`
- `getTests`
- `getTrivialQuestion`
- `getUsers`
- `findUsers`
- `getAttendanceEvents`
- `sendAttendanceEvent`
- `removeAttendanceEvent`
- `getAttendanceUsers`
- `sendAttendanceUsers`
- `getNotifications`
- `markNotificationsAsRead`
- `sendNotice`
- `sendMessage`

### `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.

### `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. For compatibility with other functions, this function returns a number > 0 (currently 1) on success, and a number <= 0 (currently 0) on error.

### `getCourses`

Returns the list of courses to which the user belongs.

- Call parameters:
  - wsKey: string, identifier returned by `loginByUserPasswordKey` or `loginBySessionKey`.
- 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:
  - wsKey: string, identifier returned by `loginByUserPasswordKey` or `loginBySessionKey`.
  - courseCode: integer.
- 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:
  - wsKey: string, identifier returned by `loginByUserPasswordKey` or `loginBySessionKey`.
  - courseCode: integer.
- 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 ⇒ it was impossible to satisfy all the requested changes, no change performed. If not 0 ⇒ all the requested changes have been performed with success.
  - 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:
  - wsKey: string, identifier returned by `loginByUserPasswordKey` or `loginBySessionKey`.
  - fileCode: integer, corresponding to:
    - an element `<code>` of the XML tree returned by `getDirectoryTree`.
    - the value of `eventCode` returned by `getNotifications` if `eventType` is documentFile or sharedFile.
    - the value of `eventCode` returned by `getNotifications` if the requester is a teacher and `eventType` is marksFile.
- 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:
  - wsKey: string, identifier returned by `loginByUserPasswordKey` or `loginBySessionKey`.
  - fileCode: integer, corresponding to:
    - an element `<code>` of the XML tree returned by `getDirectoryTree`.
    - the value of `eventCode` returned by `getNotifications` if the requester is a student and `eventType` is marksFile.
- 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:
  - wsKey: string, identifier returned by `loginByUserPasswordKey` or `loginBySessionKey`.
  - courseCode: integer.
- 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: 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.

### `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:
  - tags: 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.
  - questions: 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.
  - answers: 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).
  - questionTags: 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.
  - answers: 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,...) 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.

### `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:
  - wsKey: string, identifier returned by `loginByUserPasswordKey` or `loginBySessionKey`.
  - courseCode: integer.
- 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. On error, this code will be <= 0.

### `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. On error, this code will be <= 0.

### `getAttendanceUsers`

Returns the list of users (students) in an attendance event.

- 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.
- 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. 1 on success, 0 on error (for example, if the event does not exist).
  - 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:
  - wsKey: string, identifier returned by `loginByUserPasswordKey` or `loginBySessionKey`.
  - courseCode: integer.
  - body: string, body of the message.
- 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.