Integrate We Are with any learning management system

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)	https://your-lms-url.com/course/activityId-123456789	The Activity ID of the AU being launched. Often a URL.

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)	https://your-lms-url.com/course/activityId-123456789	The Activity ID of the AU being launched. Often a URL.
fetch	String (URL-encoded)	https://your-lms-url.com/fetch	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. If specified, we use this instead of any API key set in the configuration by the customer.
endpoint	String (URL-encoded)	https://your-lms-url.com/xapi	A URL to the LMS listener location for xAPI requests to be sent to. If specified, we override any API URL set in the config by the customer.

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