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 or Premium account – 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. For premium accounts the maximum group size is limited. For license accounts no limits on group sizes exist.

  • A main account with appropriate permissions – There will be one main account in Drillster one whose behalf the API calls will be made. This account should have the appropriate permissions to manage groups and to create user accounts. Also the organization linked to the account must be configured such that user can be added to groups with prior permission from those users. Please contact Drillster Support if you are not sure whether your account is set up correctly.

  • 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 appriopriate API calls. The LMS users who will be using Drillster learning activities must have access to www.drillster.com in order to access those learning 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.

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:

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. Authentication is done 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 3rd party system 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.

Two scenarios

When it comes to authentication with Drillster in LMS integrations, there are usually two scenarios:

  1. There is only a single instance of the LMS – In case of a single instance, there is no need to automate the OAuth handshake. The integrator can just ask Drillster Support to register the application with a specific administrative account in Drillster and generate an OAuth access token that the LMS can use for all of its API requests. This usually simplifies the integration.

  2. There are multiple instances of the LMS – For LMS system that are sold to companies or schools it is possible to create an integration that allows administrators of the LMS to link their LMS instance to their own administrative Drillster account. In other words: the LMS administrator performs the OAuth handshake themselves, without any involvement of Drillster Support or the LMS manufacturer. This is a more involved integration, but it can provide a robust coupling between Drillster and any number of LMS instances.

If there is just a single instance of the LMS, it is probably easiest to let Drillster Support register the application, and generate an OAuth token for all subsequent API requests.

Please be aware that non-expiring OAuth tokens are no longer supported. Generated OAuth tokens have a limited validity, but are always accompanied by a refresh token so that a new token may be obtained. See our OAuth documentation for more information.

If there will be multiple instances, the integration should include instructions for the LMS' administrators on how to register an API application with Drillster, and a facility to enter the Drillster client ID and client secret into the LMS. Subsequently the LMS should be capable of performing the OAuth handshake, effectively authorizing the use of a specific administrative Drillster account by the LMS. Please refer to our OAuth documentation to learn how to build such an integration.

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

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 her 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 exception correctly.

Assuming that a valid OAuth token is available, the LMS can set up a new user by sending a PUT request to https://www.drillster.com/api/2/user with a JSON document containing the details for the new user. For example:

PUT https://www.drillster.com/api/2/user
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJXSHJrck9DMFNEcWY2VjNXYVRrblpRIiwiZXhwIjoxNDYzMDY1MDkyLCJhdXRob3JpdGllcyI6WyJST0xFX1VTRVIiXSwianRpIjoiZDMyNDQ1YzEtMDAxYi00ZTkyLTgxOWMtOGUxZDcyMGQ1N2RmIiwiY2xpZW50X2lkIjoiZGNlOWM0ZDFiMTZkNGRjOGIzNDI4NjlhM2ZlNTliYjkiLCJzY29wZSI6WyJST0xFX1VTRVIiXX0.QknsrlC7BFYukHCsFhL-XGT10j8dpOcjX1yB4_bOz9k
{
  "emailAddress": "jane.doe@example.com",
  "name": "Jane Doe"
}

It is possible to include the locale and time zone for the new user as well. If these values are omitted, they are copied from the stored values for the account on whose behalf the API call was made. This means that unless you specify a locale and/or timezone in your request, all users you set up will be in the same locale and timezone as the administrative Drillster account.

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

{
  "userId": "7qr6JFBZR27rLMXiqX0srg"
}

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": "exists",
  "description": "User already present",
  "userId": "7qr6JFBZR27rLMXiqX0srg"
}

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 user endpoint.

Adding users to groups

Drillster's groups provide the 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:

  • A valid OAuth token. The same token used to create the user account can be used here.
  • 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 PUT user API call.

The user is added to the group as follows:

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

Or, with some example codes:

PUT https://www.drillster.com/api/2/group/0kIpT-yh7l6dF0w4EWkRYaB-0wzeHAJzM6vlL1te6wI/members/7qr6JFBZR27rLMXiqX0srg
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJXSHJrck9DMFNEcWY2VjNXYVRrblpRIiwiZXhwIjoxNDYzMDY1MDkyLCJhdXRob3JpdGllcyI6WyJST0xFX1VTRVIiXSwianRpIjoiZDMyNDQ1YzEtMDAxYi00ZTkyLTgxOWMtOGUxZDcyMGQ1N2RmIiwiY2xpZW50X2lkIjoiZGNlOWM0ZDFiMTZkNGRjOGIzNDI4NjlhM2ZlNTliYjkiLCJzY29wZSI6WyJST0xFX1VTRVIiXX0.QknsrlC7BFYukHCsFhL-XGT10j8dpOcjX1yB4_bOz9k

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

{
  "id" : "added"
}

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

{
  "id" : "already_member"
}

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.

Requesting user access

The next step in the integration is to provide a seamless experience for the user. If users are presented with a drill or test 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 request a password.

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 host system do not have to log in into Drillster. In fact, these users do not even have to know their Drillster credentials.

From a high level, the mechanism works as follows:

  1. The LMS system sends an authentication request for a given user ID to the Drillster API.

  2. Drillster checks that the user making the API call has the permission to let the requested user in into Drillster. In practice this means that the proxied user must be 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 URL and a unique token. The token acts as a one-time login for that user.

  4. The LMS system is then able to embed widgets with a fully authenticated session by appending the token to the URL of the widget. Note that strictly speaking this is not a “single sign-on” solution, but rather a delegated (or proxied) login. Once an authenticated session has been established for the user, further tokens are ignored. However, a token can only be used once to start a new session.

An access token can be retrieved by having the LMS make the following GET request:

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

Or, with some example data:

GET https://www.drillster.com/api/2/access/7qr6JFBZR27rLMXiqX0srg
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJXSHJrck9DMFNEcWY2VjNXYVRrblpRIiwiZXhwIjoxNDYzMDY1MDkyLCJhdXRob3JpdGllcyI6WyJST0xFX1VTRVIiXSwianRpIjoiZDMyNDQ1YzEtMDAxYi00ZTkyLTgxOWMtOGUxZDcyMGQ1N2RmIiwiY2xpZW50X2lkIjoiZGNlOWM0ZDFiMTZkNGRjOGIzNDI4NjlhM2ZlNTliYjkiLCJzY29wZSI6WyJST0xFX1VTRVIiXX0.QknsrlC7BFYukHCsFhL-XGT10j8dpOcjX1yB4_bOz9k

An example of a typical response:

{
  "url": "https://www.drillster.com/?oauth_token=l1ko49urumvkgnZ8",
  "token": "l1ko49urumvkgnZ8"
}

The token should be picked up from the response message, and appended to any Drillster URLs with content directed at the current LMS user, such as drill widgets or test widgets. It is also possible to forward the user to any page in the Drillster application and give the user a fully authenticated session.

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

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 a drill widget or test widget on the page. These widgets are implemented as an iframe and they can be included inside a page or in a CSS overlay just like on the Drillster website.

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 drill widget looks like this:

<iframe src="https://www.drillster.com/widget/drill/CZ_nPz74RJ2zFotkYzaUJw" width="940" height="395" scrolling="no" frameborder="0"></iframe>

The trick to display this widget in an authenticated session is by altering the URL in the embed code by appending the access token. The URL in the above example can be augmented as follows:

https://www.drillster.com/widget/drill/CZ_nPz74RJ2zFotkYzaUJw?oauth_token=l1ko49urumvkgnZ8

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.

Apart from drill widgets, there are test widgets as well. Embedding these works in exactly the same way, except that the URL in the embed code is slightly different and uses a “test key” instead of a drill code. 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. An example of a test widget URL:

https://www.drillster.com/widget/test/lktNe5DuR8qqRYrii7ukVg

For test widgets, the URL should have the token added to it as well.

There are many ways to tweak the look and feel of these widgets to make them fit into the LMS environment as best as possible, including the option to set a custom cover on each drill or test. Please see the widget documentation for details.

The best results are achieved with a UTF-8 character encoding. If you are using MS-Excel to export spreadsheets to CSV format, please select the “Windows text” CSV variant.

If you require automatic uploads of content, file uploads are probably not practical. For fully automated integrations, please consider implementing the Drillster API.