Result notifications

Automatically pushing student results to another system

Result notifications provide a way to push student results from the Electude LMS automatically to another system or web service through a webhook. Electude LMS site administrators can configure, test and enable notifications themselves.

When delivery fails, notifications are deferred. New attempts will be made to deliver the notification periodically, until the notification is discarded after 1 week.

1. Administrator settings

To enable result notifications, you should as an administrator:

  1. Edit the settings to match the requirements of the other system.
  2. Successfully send test notifications.

Two kinds of notifications are distinguished:

  1. New result notifications
    When a student ends a session in a learning module or when the teacher changes the result manually, this type of notification is sent. If the student session no longer responds to the Electude LMS (e.g. the student's internet connection fails) a notification is also sent after a timeout of 1 hour.
  2. Deleted result notifications
    When the teacher deletes a result, this type of notification is sent.

Available data formats are:

If LTI 1.3 is used for external access, then only LTI Assignment and Grade Services v2.0 is available and automatically selected.

1.1. URL-encoded and JSON settings

These parameters can be set separately for both new and deleted result notifications:

  • HTTP Method
    Notifications can be sent using one of these methods:
    • POST
    • GET (only available for URL-encoded)
    • PUT
    • DELETE
    • PATCH
  • Target URL
    This is the endpoint of the web service you want to connect to. Both HTTP and HTTPS are currently supported, but we strongly advise to only use secure URLs, since sensitive data is transmitted. Note that when secure URLs are used, the certificates used have to be signed by a trusted certificate authority. Notifications to servers with for example self-signed certificates will fail.

These key-value pairs are passed in every notification:

key type description
user string Unique username of the student.
firstname string First name of the student.
surname string Surname of the student.
email string Email address associated with the student account.
module integer Unique number that identifies the module. This number is also used in the URL of the module.
title string Name of the module in the default site language. If not available, this is empty.
type string Type of module, either 'lesson', 'test', 'quiz', 'simulation', 'task', 'file', 'link' or 'other'.
level integer Level of the module, either 1, 2, 3, 4 or null.
weight string Maximum score that can be achieved in a module. This usually depends on the number of questions the module contains.

The values below are only passed for new result notifications:

key type description
finished string Either 'true' or 'false', indicates whether the student is busy or has finished the module.
progress integer Indicates the progress the student has made in the module (between 0 and weight).
relprogress real Indicates the progress the student has made in the module (between 0 and 1).
score real Indicates how many points the student has scored by answering questions correctly (between 0 and weight).
relscore real Indicates how many points the student has scored by answering questions correctly (between 0 and 1).
session integer Number of times the student has opened the module.
duration string Total amount of time in 'hours:minutes:seconds'.
start string Date and time the module was opened for the first time (ISO 8601 in UTC, 'YYYY-MM-DDThh:mm:ssZ').
update string Date and time the module was opened for the last time (ISO 8601 in UTC, 'YYYY-MM-DDThh:mm:ssZ').
finish string Date and time the module was finished by a student (ISO 8601 in UTC, 'YYYY-MM-DDThh:mm:ssZ').
success string Either 'true', 'false' or null, only applies to tests.

If the data is URL-encoded, the keys and values are combined into key=value string parts that are joined together by ampersands (&). If JSON is selected, the key-value pairs are wrapped inside a JSON-object.

1.2. Tin Can / xAPI settings

Tin Can / xAPI is a technical specification to communicate learning experiences. The specification can be found here. With result notification you can connect the Electude LMS to your Learning Record Store (LRS). The Electude LMS then acts as a Learning Record Provider (LRP) that sends data to your LRS.

For Tin Can / xAPI only new result notifications are supported. You only have to specify the LRS endpoint. We append 'statements' to this endpoint and POST the data to the resulting URL, in accordance with the xAPI specification. For example, when you specify the endpoint:

https://your-lrs.com/xAPI/

the data are posted to:

https://your-lrs.com/xAPI/statements

1.3. General settings

All result notifications share these general parameters:

  • Username and password
    This is used for HTTP authentication. These authentication methods are supported and automatically detected:

    • Basic
    • Digest
    • NTLM
    • SPNEGO

  • Custom HTTP headers
    This allows you to set (multiple) custom headers sent in the HTTP request. They are separated by new lines.
    For Tin Can / xAPI these headers are always appended:

    X-Experience-API-Version:1.0.0
Content-Type: application/json

  • Module filter
    This allows you to exclude or include only certain types of modules. When only the checkbox of 'tests' is checked, notifications are only sent when students finish tests.

1.4. Sending test notifications

When you change parameters, result notifications will be inactive. You have to successfully send test notifications to activate notifications (again). This is done by clicking the button on the administrator settings page and submitting the values used in the tests. Every time both a new and a deleted result notification are sent.

2. Accepting notifications

You need to set up a server to receive and accept the notifications that are sent. We expect a response with 2xx HTTP status code (greater than or equal to 200 and less than 300). When our server receives such a response, it considers the notification to be delivered successfully. It does not look at the body of the response.

Note that redirects (3xx responses) are not allowed. The URL specified should respond directly.

We need to receive the response within 10 seconds: there is a 5-second timeout for the connection phase and a 5-second response timeout. Therefore, we recommend that you handle accepting and replying to notifications separately from processing them, and that you generate a response with 2xx HTTP status when a notification is stored.

2.1. Retries and duplicate notifications

If the notification delivery fails, or in case it is not possible to determine whether the message was delivered successfully or not, notifications are sent multiple times. This at-least-once delivery rule means that you may receive the same notification multiple times.

The system continues retrying for one week. The first retry will occur after approximately 20 minutes. The time when a retry is made doubles with every attempt, retry n is made after 10 * 2^n minutes: the second retry will occur after 40 minutes, the third after 80 minutes and so on until the 10th retry is made after 10240 minutes.

Notifications that cannot be delivered are discarded after approximately one week, after the 10th automated retry.

Deferred notifications are listed below the administrator settings for result notifications. You can resend these notifications manually and inspect the HTTP request and response to solve any issues.

When notifications are disabled, any deferred notifications are removed.

2.2. Notification ordering

Due to the way resends work, notifications may not be delivered in sorted order. In general however, the first attempt to deliver a notification will be nearly real-time.