Introduction
You can integrate We Are with any system, which allows you to seamlessly incorporate your engaging stories into your learning content. In this guide, we will walk you through the process of setting up the integration to get xAPI statements directly into your Learning Management System (LMS).
Getting started
If your LMS supports the newest standards in xAPI with cmi5 (check with your LMS provider), you can skip step 2 and 3.
Step 1: Create an integration
Go to https://studio.wearelearning.io/dashboard/settings/integrations. Add a Custom xAPI
integration
(Optional) Step 2: Add the API Key to We Are Learning
Get an API Key from your LMS. For some it will be in the settings, and for others it might require talking with support. It will look something like this: NGQ1MDgwOWIyYTZhM***.
Paste the API key provided by your LMS into the API KEY input field.
(Optional) Step 3: Add the API URL from your LMS
Get an API URL from your LMS. Paste it into the API URL input field.
Step 4: Publish and share your Story with your integration
Open the context menu on your Story, and click share.
Publish (if it’s not already published) and select your integration!
You’re done! You will now receive information regarding completions about your employees or users directly.
Technical documentation
Technical details (read this if you’re the techie making sure your system can receive data)
Hello techie! You’re about to make sure your system works with We Are, which we absolutely appreciate. If you have questions while verifying, don’t hesitate to drop us a message at [email protected].
Technical Introduction
Let’s get some technical lingo out of the way. We use xAPI, specifically cmi5, and do our best to follow it’s specifications. In this guide we’ll let you know how we handle connections, sending statements and more.
Where do we send the statements?
We have an adaption of cmi5 where we allow both the query parameter endpoint
as well as specifying the API url directly in We Are.
The endpoint
query parameter has precedence.
Authentication
We support fetch
from cmi5, as well as specifying the API key directly in We Are.
The fetch
query parameter has precedence.
Required Query Parameters
Name | Data type | Example value | Description |
actor | JSON | {"objectType": "Agent","account": {"name": "1625378"}}
| A JSON object of objectType of Agent (as defined in xAPI) that identifies the learner launching the We Are so we will be able to include it in xAPI requests.
We require this value to so you can identify the user on completions.
Your LMS SHOULD create this parameter with an object that is specific to the LMS that does NOT include sensitive personal identifiable information of the learner. |
activityId | string (URL-encoded) | The Activity ID of the AU being launched. |
Optional Query Parameters
Name | Data type | Example value | Description |
registration | String (URL-encoded) | this-is-my-registration-id | A Registration ID corresponding to the learner's enrolment for the activity being launched. |
sessionId | String (URL-encoded) | this-is-my-sessionid | Generated by the LMS. Must be recorded by the LMS prior to launching a We Are Story. |
activityId | String (URL-encoded) | The Activity ID of the AU being launched. | |
fetch | String (URL-encoded) | The fetch URL is used by We Are to obtain an authorization token created and managed by the LMS. We use this to authenticate ourselves when making requests. | |
endpoint | String (URL-encoded) | A URL to the LMS listener location for xAPI requests to be sent to. |
Example request from We Are to Your LMS
{
"actor": {
"name": "987654321"
},
"verb": {
"display": {
"en-US": "Completed"
},
"id": "http://adlnet.gov/expapi/verbs/completed"
},
"object": {
"definition": {
"type": "http://adlnet.gov/expapi/activities/course"
},
"id": "https://your-lms-url.com/course/activityId-123456789",
"objectType": "Activity"
},
"timestamp": "2024-06-05T13:05:36.253062Z",
"Context": {
"Registration": "this-is-my-registration-id",
"Extensions": {
"https://w3id.org/xapi/cmi5/context/extensions/sessionid": "this-is-my-sessionid"
}
}
}
Links that are nice to have
cmi5 specification: https://github.com/AICC/CMI-5_Spec_Current/blob/quartz/cmi5_spec.md#811-endpoint