Ed Integration Features

The Ed API allows you to:

  • Create and delete users in the Ed LMS
  • Add users to groups
  • List the content that is available to users, and obtain links that can be used to launch the lessons in the Ed mobile app or website.

To see the full list and description of endpoints, visit our API Docs.

Example scenario from the end-user perspective

  • Users log into your LMS or other application as normal.
  • Lessons created in Ed are listed (via data from the Ed API).
  • The user clicks a lesson they are interested in, and are taken directly to the Ed lesson.
  • When the user completes their lesson, they return to the original platform and their results are populated (again via the Ed API)

The links returned from the API are Universal Links, which can open the lesson on the web or via the Ed app. The decision of whether to open the app or the web version depends on the user's device. On Android or iOS, the links will either open the app or redirect the user to the App Store or Google Play to install it.

The Universal Links we provide look like the following:

https://web.edapp.com/launch-lesson?token=d655a5b5-7b86-4ef5-a053-8b591d3e5cc4&lesson=507f191e810c19729de860ea

You will notice there is a token query parameter. This is required to ensure the user is logged in correctly when they access the lesson. The tokens expire in 20 minutes, so it is important to provide users with fresh links when they use your application.

Obtaining data on lesson completion

Once a user has completed their lesson, they will return to your platform. You may wish to display that the lesson has been completed to prevent them from clicking it again, or for other analytis. This information can be retrieved from the Ed API, using the same method as listing the available lessons for a user. Of interest will be the completed and completionDate properties of the lesson. See the section "List the lessons available for a user" below.

A more detailed report that tracks user interactions at the slide level is also available. It will provide information such as how a user answered question slides and how long they spent on each slide. See the section "Getting a detailed report on the user interactions" below.

Ed Integration Details

Authentication

The Ed API uses a simple Bearer Token based authentication scheme. Tokens can be obtained from the Ed LMS and must be passed in the http Authorization header.

From the LMS the token can be found under Settings > API as follows: LMS Screenshot

A sample request using cURL and a made-up token would be

curl https://rest.edapp.com/v1/reports/activities -H 'Authorization: Bearer a56cd0ac-11c2-11e6-a148-3e1d07dcef63'

User Management

Creating a user

To create a user, issue a POST request to /users:

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer a56cd0ac-11c2-11e6-a148-3e1d05defe78" -d '  {
    "username": "lthompson44@mcmail.cc",
    "email": "lthompson44@mcmail.cc",
    "usergroups": [
      "56d5bd3d1bab678c1d914fe6",
      "56d850b0e99dc8772b59c7fa"
    ],
    "firstName": "John",
    "lastName": "Thomson"
  }' "https://rest.edapp.com/v1/users"

The API will return a JSON document representing the new user you just created, i.e.

{
    "id": "574642869fa99d9b6609b0f4",
    "username": "lthompson44@mcmail.cc",
    "email": "lthompson44@mcmail.cc",
    "usergroups": [
      "56d5bd3d1bab678c1d914fe6",
      "56d850b0e99dc8772b59c7fa"
    ],
    "firstName": "John",
    "lastName": "Thomson"
  }

Updating a user

The id that is returned from the above call can be used to make changes to the user. For example, to remove Mr Thomson from one of the usergroups:

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer a56cd0ac-11c2-11e6-a148-3e1d05defe78" -d '  {
    "id": "574642869fa99d9b6609b0f4",
    "username": "lthompson44@mcmail.cc",
    "email": "lthompson44@mcmail.cc",
    "firstName": "John",
    "lastName": "Thomson",
    "usergroups": [
      "56d850b0e99dc8772b59c7fa"
    ]
  }' "https://rest.edapp.com/v1/users"

Passing the id field instructs the API to perform an update operation rather than an insertion. Like in the above case, the API will return a JSON document representing the updated user. To delete a user, a slightly different path is used with the HTTP DELETE method:

curl -X DELETE -H "Content-Type: application/json" -H "Authorization: Bearer a56cd0ac-11c2-11e6-a148-3e1d05defe78" "https://rest.edapp.com/v1/users/56d671d226a8eaf178ca6998"

The following document will be returned if the deletion is successful:

{"success":true}

User group management

User groups can be created/modified/deleted directly from the API. This can be useful to keep the user groups in Ed in sync with your organisation groups in another platform.

Creating a user group

Similarly to creating a user, submit a POST to /usergroups:

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer a56cd0ac-11c2-11e6-a148-3e1d05defe78" -d '  {
    "name": "Sales",
    "users": ["574642869fa99d9b6609b0f4", "570f82dce0c6bf6b7a0cb61d"],
    "courses": ["507f191e810c19729de860ea", "507f191e810c19729de860eb"]
  }' "https://rest.edapp.com/v1/usergroups"

As with users, the API will return a JSON document representing the created user group and it will contain the ID:

{
  "id": "5645544c053ab4d30ecdc825",
  "name": "Sales",
  "users": ["574642869fa99d9b6609b0f4", "570f82dce0c6bf6b7a0cb61d"],
  "courses": ["507f191e810c19729de860ea", "507f191e810c19729de860eb"]
}

Adding and removing users from a group

Users can be removed or added from the group by updating the group directly. For example to remove all users from a group:

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer a56cd0ac-11c2-11e6-a148-3e1d05defe78" -d '  {
  "id": "5645544c053ab4d30ecdc825",
  "name": "Sales",
  "users": [],
  "courses": ["507f191e810c19729de860ea", "507f191e810c19729de860eb"]
} ' "https://rest.edapp.com/v1/usergroups"

Deleting a user group

This works similarly to users:

curl -X DELETE -H "Content-Type: application/json" -H "Authorization: Bearer a56cd0ac-11c2-11e6-a148-3e1d05defe78" "https://rest.edapp.com/v1/usergroups/5645544c053ab4d30ecdc825"

Result:

{"success":true}

Content management

Creating content

Content is created using the Ed authoring tool on the LMS at admin.edapp.com.

List the lessons available for a user

Available content for a user can be retreived using the /users/{id}/courses endpoint:

curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer a56cd0ac-11c2-11e6-a148-3e1d05defe78" "https://rest.edapp.com/v1/users/56d671d226a8eaf178ca69b7/courses"

The returned JSON will be an array of available courses for that user. Within each course is a listing of the lessons available within that course. To launch lessons in the Ed app, the launchURI property of the lesson can be used:

[{
  "id": "507f191e810c19729de860ea",
  "unlocked": true,
  "unlockedDate": "2016-02-09T05:54:23.691Z",
  "completed": false,
  "completedDate": "2016-05-09T05:54:23.691Z",
  "opened": true,
  "openedDate": "2016-05-09T05:51:23.691Z",
  "title": "Introduction to ACME",
  "lessons": [{
    "id": "507f191e810c19729de860eb",
    "title": "Introduction to ACME Explosive Tennis Balls.",
    "launchURI": "https://web.edapp.com/launch-lesson?token=d655a5b5-7b86-4ef5-a053-8b591d3e5cc4&lesson=507f191e810c19729de860ea",
    "unlocked": true,
    "unlockedDate": "2016-02-09T05:54:23.691Z",
    "completed": false,
    "completedDate": "2016-05-09T05:54:23.691Z",
    "opened": true,
    "openedDate": "2016-05-09T05:51:23.691Z"
  },{
    "id": "507f191e810c19729de860eb",
    "title": "Anatomy of an ACME Product.",
    "launchURI": "https://web.edapp.com/launch-lesson?token=d655a5b5-7b86-4ef5-a053-8b591d3e5cc4&lesson=507f191e810c19729de860eb",
    "unlocked": true,
    "unlockedDate": "2016-02-09T05:54:23.691Z",
    "completed": false,
    "completedDate": "2016-05-09T05:54:23.691Z",
    "opened": true,
    "openedDate": "2016-05-09T05:51:23.691Z"
  }]
},{
  "id": "507f191e810c19729de860eb",
  "title": "Life at ACME",
  "lessons": [{
    "id": "507f191e810c19729de860ed",
    "title": "Introduction to the ACME campus, building A",
    "launchURI": "https://web.edapp.com/launch-lesson?token=d655a5b5-7b86-4ef5-a053-8b591d3e5cc4&lesson=507f191e810c19729de860ed",
    "unlocked": true,
    "unlockedDate": "2016-02-09T05:54:23.691Z",
    "completed": false,
    "completedDate": "2016-05-09T05:54:23.691Z",
    "opened": true,
    "openedDate": "2016-05-09T05:51:23.691Z"
  }]
}]

If the launchURI link is included in a page or app, the user can tap it to launch the lesson in Ed.

Getting a detailed report on the user interactions

For a more detailed view of how end-users interacted with your content, a user report is available. It is accessed via the /reports/user/{id}/course/{id} endpoint.

curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer a56cd0ac-11c2-11e6-a148-3e1d05defe78" "https://rest.edapp.com/v1/reports/user/56d671d226a8eaf178ca69b7/course/507f191e810c19729de860ea"

The result document will contain detailed data about every lesson within a course that the user interacted with:

{
  "id": "507f191e810c19729de860ea",
  "title": "Introduction to ACME",
  "unlocked": true,
  "unlockedDate": "2016-02-09T05:54:23.691Z",
  "completed": false,
  "completedDate": "2016-05-09T05:54:23.691Z",
  "opened": true,
  "openedDate": "2016-05-09T05:51:23.691Z",
  "lessons": [{
    "id": "507f191e810c19729de860eb",
    "title": "Introduction to ACME Explosive Tennis Balls.",
    "unlocked": true,
    "unlockedDate": "2016-02-09T05:54:23.691Z",
    "completed": false,
    "completedDate": "2016-05-09T05:54:23.691Z",
    "opened": true,
    "openedDate": "2016-05-09T05:51:23.691Z",
    "duration": 156.78,
    "slides": [{
      "name": "1",
      "interactions": [{
        "date": "2016-05-09T05:51:22.368Z",
        "type": "view",
        "duration": 6.785
      },{
        "date": "2016-05-09T05:51:27.691Z",
        "type": "slide",
        "result": {
          "correct": true,
          "too_slow": false
        }
      }]
    },{
      "name": "2",
      "interactions": [{
        "date": "2016-05-09T05:52:22.368Z",
        "type": "view",
        "duration": 9.672
      },{
        "date": "2016-05-09T05:52:27.691Z",
        "type": "slide",
        "result": {
          "correct": false,
          "too_slow": false
        }
      }]
    }]
  }
}

How to use Single Sign-On

Ed supports authenticating users on the app with SAML 2.0.

To configure single sign-on, or SSO, navigate to Settings > Single Sign-On in the LMS. Enable SSO and fill in the fields. You will need to obtain the SAML URL, Entity ID, and Certificate from the application or system you intend to use for authentication. The Company ID can be a string of your choosing, but keep in mind that users will have to enter this to log into the app.

SSO details on LMS

To log into the app, users will enter your company ID on the Single Sign On screen in the app. They will then be redirected to your identity provider login page, where they will enter their credentials. After authentication, the user will be redirected back into the Ed app, and the login process will be complete.

Entering the company ID in Ed

Authenticating with an example SAML identity provider

Being prompted to return to Ed after authentication