xAPI: Receiving an xAPI Statement

This guide will demonstrate how to receive an xAPI statement via either an LRS or a resthook. This allows another service to receive user events as they occur on OpenLearning, e.g.

  • Page Viewed
  • Activity Section Completed
  • Page Completed
  • Course Completed
  • Post Published
  • Comment made on a Page
  • Comment made on a Post

As well as events generated by custom xAPI integrations within an OpenLearning course

API Setup

The steps in this guide make use of the OpenLearning API. To use this API you will need to register an API key (on the API website) using your OpenLearning user account. Take note of this API key, and keep it secure as it is your secret password for accessing the API. 

Once you have registered an API key, you can use the OpenLearning API from your own code or application by making HTTP requests, or use the API website to try out individual requests. Click the "Authorize" button and enter your API key to start using the "Try it out" sections of the API documentation.

Adding an LRS or Rest Hook to your Course

1. Finding your Course ID

To add an LRS or Rest Hook to your course, you will need to find out your Course ID.

The "GET /courses/" API allows you to search for your Course ID by providing the URL or OpenLearning path of your course. Click "Try it out" next to the "GET /courses/" documentation and enter your course URL in the "url" field. Click "Execute" to search for this course and make note of the "id" field in the Response body:

{
  "meta": {
    "status": 200
  },
  "data": [
    {
      "id": "<YOUR COURSE ID>",
      "url": "https://www.openlearning.com/courses/...",
      "title": "Example Course",
      "summary": "A brief summary of the course...",
      "image": "https://www.example.com/course-image.png",
      "self_paced": true
    }
  ]
}

 

Now that you have the Course ID, you can use this to refer to your course when using the other /courses/ APIs.

2. Adding an LRS or Rest Hook via the API

To add an LRS or Rest Hook to your course (for which you have now found the Course ID), you can use the "POST /courses/{course_id}/xapi-integrations/" API.

Click "Try it out" next to the "POST /courses/{course_id}/xapi-integrations/" documentation and fill out the following parameters:

Setting up an LRS:

  • "name" is the name of your integration, you can fill this in with any descriptive text
  • "url" is the URL of your LRS, where xAPI statements will be sent
  • "key" is the authentication key for your LRS
  • "secret" is the authentication password for your LRS
  • "rest_hooks_url" is not required for an LRS, and does not need to be specified

Setting up a Rest Hook:

Setting up a Webhook/Rest Hook is the same as setting up an LRS, except:

  • "url" is a URL which expects a "/statements/" sub-path suffix to which xAPI statements are sent (as per the xAPI specification). If your web service is not expecting a "/statements/" suffix, you can override this URL using the "rest_hooks_url" parameter.
  • "rest_hooks_url" can be optionally specified to override the URL parameter, and xAPI statements will instead be sent to this URL (exactly as it has been specified, without a "/statements/" path suffix). If you are expecting to receive the webhook/rest hook at this particular URL, specify this URL in both the "url" and "rest_hooks_url" fields.

N.B. "key" and "secret" are sent via HTTP Basic Auth, which may be checked by the webhook/rest hook service.

In addition to these parameters, you will need to specify the "course_id" from the previous step.

3. Configuring which statements are sent to the LRS or hook

In your course settings, under Course Setup > Advanced you will find a section labelled "xAPI Settings".

Under these settings the "Active Integrations" will be listed. If Step 2. above was successful, your LRS or Rest Hook will be listed here.

Additional settings for xAPI statements are covered in this article: xAPI: Configuring xAPI Statements.

The specified xAPI statements will now be sent to your LRS or hook as a JSON HTTP Request (in xAPI format).

Reply Oldest first
  • Oldest first
  • Newest first
  • Active threads
  • Popular
Like Follow
  • 5 mths agoLast active
  • 49Views
  • 1 Following