Creating a typical LMS integration

Drillster lends itself very well for integration into third party learning management systems (LMS). This way Drillster's adaptive memorization and testing capabilities can greatly enhance an integrated learning environment.

  • Practice drills and do tests as regular learning activities inside the LMS
  • Keep track of the proficiency levels and progress of your students
  • Provide a seamless integration between Drillster and the host platform

Prerequisites

The following things are required in order to make the integration work with an LMS as described in this document:

  • Drillster Education or Business license – The connection between the LMS and Drillster makes use of Drillster's group functionality, which requires a paid account. Also, the integration will automatically add user accounts to groups in case no corresponding Drillster account exists for the LMS user.

  • A service account with appropriate permissions – At least one service account is required to make the API calls. This account should have the appropriate permissions to manage groups and to create user accounts. More information can be found in the service account documentation.

  • Internet access ‐ This one sounds like a no-brainer, but it is very important. The LMS instance should have outbound access to www.drillster.com (ports 80 and 443). This will allow it to make the appropriate API calls. The LMS users who will be using Drillster learning activities must have access to www.drillster.com in order to access those earning activities. For drills containing audio or video, additional hosts are accessed. In most educational or business environments this is no problem. In general, any modern browser with internet access (direct or proxied) will do just fine.

💡 Good to know

The flow described here relies on the ability to keep the administrative OAuth token (and associated client secret) a secret from the end user. This means that a server side component is required, and that for instance a pure Javascript implementation that runs inside the learner's browser cannot be made to function securely.

A typical integration consists of a couple of components:

  • Connecting to the Drillster API
  • Automatically setting up user accounts in Drillster
  • Automatically adding users to groups in Drillster
  • Single sign-on
    • Delegated login
    • OAuth 2.0 or OpenID Connect identity service
    • Which SSO method to use?
  • Presenting drills to your users

The aim of this document is to provide guidelines and best practices for making such an LMS integration. It is by no means an exhaustive description of what sort of integrations are possible. Also, this document assumes that the actual drill content will be created in Drillster by administrators of the LMS. There are ways to automate the loading of drill content, but that is beyond the scope of this document.

Connecting to the Drillster API

In order to create user accounts in Drillster, facilitate a seamless login or to retrieve proficiencies, an API connection between the LMS and Drillster must be created.

Drillster has a REST API that uses JSON as the data protocol. Requests to the API are authorized using the OAuth 2.0 mechanism. The use of OAuth means that API requests can be made on behalf of a Drillster user account as and when that user has given permission to the LMS to access the account.

In a typical LMS integration, the API requests are usually not directed at the individual user accounts, but rather at an administrative account in Drillster. This greatly simplifies things, as only a single account authorization is required.

To perform API requests on behalf of a specific user, please refer to the OAuth 2.0 documentation.

Automatically setting up user accounts

Drillster is all about long term retention of knowledge. This means that it is imperative to track individual user progress, and in order to do that, a user account must exist in Drillster for each LMS user that needs to make use of Drillster functionality.

To set up a user account, just two things are required:

  1. The user's real name
  2. The user's email address or a previously agreed third party ID

Drillster does not use the email address as the primary key for the account, but assigns a unique alphanumeric user ID to each account. This user ID is returned in the response of the API call. It is entirely possible that the user changes their email address in Drillster, or adds additional email addresses to the account. Even the name can be changed by the user, but the user ID will remain constant.

Another possibility is that the user already exists in Drillster. The user could have a pre-existing account, or the LMS may not have recorded that it set up the account earlier. This is no problem, but it is important that the LMS deals with exceptions correctly.

Assuming that a valid OAuth token is available, the LMS can set up a new user by sending a request to POST /api/2.1.1/users with parameters containing the details for the new user. For example:

POST https://www.drillster.com/api/2.1.1/users
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJXSHJrck9DMFNEcWY2VjNXYVRrblpRIiwiZXhwIjoxNDYzMDY1MDkyLCJhdXRob3JpdGllcyI6WyJST0xFX1VTRVIiXSwianRpIjoiZDMyNDQ1YzEtMDAxYi00ZTkyLTgxOWMtOGUxZDcyMGQ1N2RmIiwiY2xpZW50X2lkIjoiZGNlOWM0ZDFiMTZkNGRjOGIzNDI4NjlhM2ZlNTliYjkiLCJzY29wZSI6WyJST0xFX1VTRVIiXX0.QknsrlC7BFYukHCsFhL-XGT10j8dpOcjX1yB4_bOz9k
emailAddress=jane.doe@example.com
name=Jane Doe

It is possible to specify additional details of the account. Please refer to the API documentation for more information.

A successful response would have an HTTP response code 200 and returns the generated user ID as follows:

{
  "type": "USER",
  "id": "3mhUfNhHQzqTCN0oZLcsJg"
}

If the user already exists, an error response is returned with HTTP response code 400 (Bad request). The response does contain the user ID:

{
  "id": "account_exists",
  "description": "The given email address is linked to an existing account",
  "userId": "3mhUfNhHQzqTCN0oZLcsJg"
}

It is important to pick up the user ID in either case, as it is required in order to add this user to the appropriate groups.

For exact details about this API endpoint, please see the specification of the API's users endpoint.

Automatically adding users to groups in Drillster

Drillster's groups provide a mechanism to allow access to predefined sets of drills or tests to a group of users. A group in Drillster in its simplest form is a collection of drills assigned to a collection of users. Once learning material is structured in groups, it becomes possible to set learning objectives, assign tests and to run various reports. Drillster's groups mechanism lends itself extremely well for integration with an LMS.

For the scope of this document it is assumed that the groups have already been created and filled with content (i.e. the drills or tests). Groups can be created in Drillster by the administrative user. It is also assumed that the LMS has knowledge of the group codes (unique IDs for each group) relevant for each user. This should probably be part of the course building process where a Drillster learning activity is included in the LMS.

In order to add a user to a group, the following information is required:

  • The group code. Group codes can be obtained from the Drillster website, where groups are created and managed.
  • The user ID. This is the ID that was obtained from the POST /api/2.1.1/users API call.

The user is added to the group as follows:

PUT https://www.drillster.com/api/2.1.1/group/{group_code}/members/{user_id}

Or, with some example codes:

PUT https://www.drillster.com/api/2.1.1/group/0kIpT-yh7l6dF0w4EWkRYaB-0wzeHAJzM6vlL1te6wI/members/7qr6JFBZR27rLMXiqX0srg

A successful response would have an HTTP response code 200 and returns a message stating that:

{
  "description": "The user has been invited to the group."
}

If the user was already part of the group, an HTTP response code 400 will be returned, with the following message:

{
  "id": "already_member",
  "description":"A user with user ID7qr6JFBZR27rLMXiqX0srg is already invited to group0kIpT-yh7l6dF0w4EWkRYaB-0wzeHAJzM6vlL1te6wI"
}

Note that it is important to separate this error from other errors, as it still signifies a positive result!

By adding the user to the group, the user now has access to all of the drills and tests contained in the group. Should the user log in into the Drillster website, he or she will see all of the drills from the group listed in the repertoire. These drills do not count toward the storage limit of a basic user account. Any drills that are added to the group later will immediately be available to all current group members.

It is possible to remove users from a group through the API as well, but that is beyond the scope of this document. For exact details about this API endpoint, please see the specification of the API's group/…/members endpoint.

Single sign-on

The next step in the integration is to provide a seamless experience for the user. If users are presented with a player widget in the LMS, Drillster does not know who that user is, unless they have logged in before. This means that Drillster will ask the user to log in, which is far from a seamless user experience. In fact, for users that have just been added through the API, there is no password set, so users are unable to log in until they configure a password.

To overcome this, Drillster supports single sign-on. There are two ways to use single sign-on (SSO):

  1. SSO through delegated login
  2. SSO through an OAuth 2.0 or OpenID Connect identity service

Delegated login

Delegated user logins provide a way for a third party to integrate Drillster into another product by way of automatically establishing a logged in user session on Drillster. That way users authenticated on the LMS do not have to log in into Drillster.

From a high level, the mechanism works as follows:

  1. The LMS system sends a delegated login request for a given user ID to the Drillster API.
  2. Drillster checks that the user making the delegated login request has the permission to let the requested user in into Drillster. In practice this means that the requested user must be a member of a group for which the calling user has administrative rights.
  3. If permissions are OK, Drillster will respond with a message containing a unique access token. The token is only valid for a short time.

An access token can be retrieved by having the LMS make a request to the GET /api/2.1.1/access/… endpoint:

GET https://www.drillster.com/api/2.1.1/access/{user-id}

Or, with some example data:

GET https://www.drillster.com/api/2.1.1/access/7qr6JFBZR27rLMXiqX0srg

An example of a typical response:

{
  "token": "eyJhbGciOiJSUzI1NiIsInR5..."
}

The token should be picked up from the response message, and used as a drl-token attribute in loading the Drillster player widget or other widgets (see next section).

For exact details about this API endpoint, please see the specification of the API's GET /api/2.1.1/access/… endpoint.

OAuth 2.0 or OpenID Connect identity service

If you are using an identity service yourself to authenticate your own users, you can use it to perform SSO on the Drillster platform. The requirement is that your identity server is OAuth 2.0 compliant, and can be used by external parties like Drillster.

For some well-known cloud-based identity services such as Microsoft Azure AD, Drillster has full support.

Even better is if your identity server complies to the 🔗 OpenID Connect standard. This is a standard on top of OAuth 2.0, and makes it even easier to connect Drillster and your LMS, because it standardizes the way that the user information is retrieved.

The process works like this:

  1. The user logs in to the LMS, using the LMS identity service
  2. The user is sent to Drillster to practice a drill
  3. The user is not logged in to Drillster yet, so he is sent to the LMS's identity service
  4. After verifying that the user was already logged in to the LMS, he is immediately sent back to Drillster, with an authorization code
  5. Drillster uses the authorization code to request the user's details (e.g. email and name) from the LMS's identity service
  6. Drillster logs the user in, and allows the user to practice the drill

Please see the article on SSO with OpenID Connect for more information.

Which SSO method to use?

If you are already using an OAuth 2.0 or OpenID Connect identity service, it is strongly recommended to use it for SSO with Drillster. It provides the highest level of security, because it authenticates the end-user.

Delegated login can be used if you don't have such an identity service. Delegated login is simple to implement, but provides a security level that is not as high as an identity service.

Presenting drills to your users

Once a user ID has been established, the user is part of one or multiple groups, and an access token has been generated, it is time for some user interaction. You can display any test or drill widget to your users by embedding the Drillster player on the page. Please see our widgets documentation for details on how to display Drillster widgets on your page, and how to include the session token.

For the scope of this document, it is assumed that the LMS has knowledge of the drill codes that are part of the group. The only variable part in the embed code is the drill code, so the URLs are easy to generate.

A typical embed code for a player widget looks like this:

<script src="https://www.drillster.com/widgets/loader.js" type="text/javascript"></script>

<div class="drl-widget drl-player" drl-code="CZ_nPz74RJ2zFotkYzaUJw" drl-token="l1ko49urumvkgnZ8"></div>

Again, please refer to our widgets documentation for details about the use of the widget loader and customization options.

If you are unable or unwilling to store the user ID beforehand, it is possbile to execute the three steps described above in rapid succession as and when you are looking to present a test or drill widget to a user. This means: ① create the user (or determine the user ID from the response if the user is already present), ② add the user to the group, ③ request an access token, ④ present a test or drill widget to the user with the token included.

The player widget is able to open tests as well as drills. Embedding these works in exactly the same way. The test keys can be extracted from the group detail screen in the Drillster application. The test key is the same for each group member.

  • Copyright © 2006–2024 Drillster BV.