Launch LRS Documentation

Launch Learning Documentation

Launch LRSLiftLift demoGoogle Data Studio

Quick start

To get started immediately the quick start section provides the basic information required. Instructions are provided in further detail in the relevant sections.

Sign in

Sign into your Launch LRS with the following default administrator credentials, you will be required to change you password on first sign in:

username: admin 
password: password

xAPI configuration

The majority of activity providers use Basic Authentication to connect to an LRS. To send an xAPI statement to Launch LRS you will need to use an endpoint, username and password.

Endpoint: The domain of your Launch LRS followed by /xapi/ with the correct protocol (HTTP or HTTPS) for your site. Depending on your activity provider you may not need the trailing forwards slash. For example:

https://lrs.example.com/xapi/

Username: Within the User page add a user for your activity provider, ensuring the username relates to the provider you’re configuring

Password: Add a strong password and make a note of it

The endpoint and credentials created can be added to your activity provider’s settings to start sending data to Launch LRS.

Users

A Launch LRS user is any person or system that connects to Launch LRS. This includes but is not limited to administrators, activity providers and other LRSs.

Administrators

Launch LRS is configured to have an initial administrator.

An administrator can:

  • view the total number stored statements in the dashboard
  • add and delete users
  • store statements in the LRS
  • view all statements in the LRS
  • view and add licences
  • configure statement mirroring and statement forwarding
  • change their own password

An administrator is not able to delete their own user from the system.

Non-administrative users

Non admin users are usually activity providers. A user can:

  • view the total number stored statements in the dashboard
  • change their own password

A user is not able to delete themselves from the system.

Adding a user

When logged in as an administrator, navigate to the Users tab

Within the Add User section at the bottom of the page enter a username and password for the new user

Choose a strong password and make a note of it. The password will not be displayed.

Only select the administrator checkbox if you want the user to have administrator privileges

Click Add

Connecting to an activity provider

Adding an activity provider within Launch LRS

An activity provider is an application that sends data to Launch LRS. The majority of activity providers use Basic Authentication to connect to an LRS.

An activity provider is a normal user of the LRS and therefore added the same way.

Within the Add User section at the bottom of the page enter a username and password for the new user

Ensure the username relates to the activity provider you’re configuring in case you wish to delete it in the future.

Choose a strong password and make a note of it, you will need to know the password to configure your activity provider. The password will not be displayed.

We recommend that at activity provider sending data to Launch LRS does not have administrator access to ensure the provider only has access to the data it sends

Activity provider configuration

Within your activity provider settings connect to Launch LRS with the username and password created. Your activity provider might refer to them as Key and Secret Key.

The URL to use is the domain of your Launch LRS followed by /xapi/, using the correct protocol (HTTP or HTTPS) for your site. Depending on your activity provider you may not need the trailing forwards slash. For example:

https://lrs.example.com/xapi/

Integrating with LinkedIn Learning

LinkedIn Learning supports xAPI version 1.0.0 and uses OAuth 2.0 client credentials flow to authenticate with Launch LRS. For more information view the LinkedIn Learning xAPI Administration Guide.

Add a provider within Launch LRS

On the user page add a new non-administrative user for LinkedIn Learning. You will need the username and password of this new user to configure the LinkedIn Learning integration.

Configure LinkedIn Learning

Log in to your LinkedIn Learning account, if you are not already in the Admin screen, select Go to Admin, then click  Me > Integration settings.

From the left-hand navigation menu, select LMS Reporting APIs.

Expand the “xAPI” section.

Click Add integration and fill out the following fields.

Integration name: A name to identify the xAPI connection, for example, Launch LRS
User type: Choose any of ID, username or e-mail
OAuth Server URL: This is the domain of your Launch LRS followed by /oauth2/token with the correct protocol (HTTP or HTTPS) for your site. For example: https://lrs.example.com/oauth2/token
Tenant Server URL: This is the domain of your Launch LRS followed by /xapi with the correct protocol (HTTP or HTTPS) for your site. For example: https://lrs.example.com/xapi
Client ID: Username for the LinkedIn Learning user previously created
Client Secret: Password for the LinkedIn Learning user previously created

Click Enable.

Licences

A Launch LRS licence plan can be purchased if additional storage is required or to access our technical support. When a licence is purchased a unique activation key will be provided. 

Adding a licence

  • Log into Launch LRS as an administrator and navigate to the Licences page
  • In the Add Licence section enter your licence key and click add

If the licence is valid it will be added to the list of licences and additional information associated with the licence will be displayed.

If the licence key is invalid, expired or already in use an error message will be displayed.

Additional licence keys may be entered to increase the total number of allowed statements.

Installation

Launch LRS has several installation options. View our installation page for instructions on how to get started with AWS CloudFormation, AWS AMI and Ubuntu. For help getting started on different platforms please contact us.

Database configuration

If a database is not specified, the Launch LRS application will use an in-memory database which will be wiped every time you restart the Launch LRS application.

For a production environment we recommend configuring the Launch LRS database on a different host to the Launch LRS application.

Prerequisites

  • An existing database server with a new database. Launch LRS supports MySQL, MariaDB, PostgreSQL, SQL Server and H2.
  • A user with full permission to the database.
  • Security of the database server configured to allow inbound traffic from the IP of your Launch LRS.

Step 1: Connect to your Launch LRS server

Step 2: Add your database configuration

Create and open an application.properties file in the same directory as the Launch LRS application, for example:

[user ~]$ sudo vi /opt/launch/lrs/application.properties

Insert the configuration below into the application.properties file, substituting the following:

dbms: mysql, sqlserver or postgresql

endpoint: URL of your database server. For internal database installations use localhost
dbname: name of the database you intend to use for Launch LRS
user: a username with full permissions to the specified database
changeMe: password for the user

spring.datasource.url=jdbc:dbms://endpoint:3306/dbname?zeroDateTimeBehavior=convertToNull
spring.datasource.username=user
spring.datasource.password=changeMe

Save and quit.

Step 3: Restart Launch LRS

[user ~]$ sudo systemctl restart launch-lrs

If you now access Launch LRS in your browser you should notice the in-memory warning message at the bottom of the screen has gone.

If you receive 502 Bad Gateway, ensure you’re credentials, endpoint and port are correct in the configuration file.

If you changed your password during the initial setup, it will have been set back to the default when the database was specified. Select manage and sign in with the following credentials:
username: admin 
password: password
You will be required to change your password on first sign in after specifying a database.

Lift Configuration

The downloaded Lift application files (within in the AWS S3 bucket if using the CloudFormation template) contain an assets folder with an example Lift configuration file, example cookie policy file and example privacy policy, along with the assets these files refer to. The example-config.json file must be renamed and edited with your own configuration, renaming other example files is optional.

If Lift has been installed using the AWS CloudFormation template, whenever any changes are made to the files, AWS CloudFront will need to be invalidated to clear the cache.

Initial configuration and provider setup

The minimum requirement for Lift is a config.json file and valid provider ID for Google, Microsoft or Facebook.

1. Rename the example-config.json to config.json

2. Add your client IDs in the provider section of the config.json file

Google
Create credentials in the Google developer console
Select Credentials in the left menu the select + Create Credentials
Choose OAuth client ID and select web application
Under Authorised JavaScript origins add the URI for your domain which will host Lift
The Client ID which is created needs to be added to the config.json file in Lift
For more information review the Google documentation.

Microsoft
For more information view the Microsoft Azure documentation.

Branding

After creating the config.json file, the following values may be changed to use your own branding.



"systemName": "Lift",
"systemDescription": "Fast and easy learning.",
"logo": "assets/launch-learning-logo.svg",
"icon": "assets/launch-learning-icon.svg",
"welcomeHeader": "Welcome to Lift",
"welcomeLead": "Fast and easy learning.",
"welcomeTextColor": "white",
"backgroundImage": "assets/launch-learning-bg.jpg",
"backgroundColorOpacity": 0.65,
"backgroundColor": "black",

Course configuration

The location of your learning resources is defined within the courses and catalogs section of the config.json file. A course can be defined in the config directly as shown in the example-config.json, or a catalog can used which specifies the location of a json file defining the individual courses.

An example json course definition for a catalog to reference can be found in assets/launch-learning-example-courses.json and is referred to in the Default catalog.

publicCatalogs

If true anyone can view your courses with the browse section of Lift without signing in. Course descriptions can also be viewed. To launch a course the user will need to sign in.

If false users need to sign in to Lift before viewing your courses.

"publicCatalogs": false,

courses

The example configuration file has one course defined directly. This may be replaced or removed. Courses defined here will appear alongside courses defined in the catalog.

If a single course is defined directly in the config.json and if there are no catalogs defined, then the course will launch directly when a user logs into the system and the user will not be taken to the platform.

"courses": [
   {
     "name": "How High is Your Healthy Eating IQ?",
     "description": "How much do you *really know* about healthy eating?\n\nTake this short interactive quiz to test your knowledge and access resources to help you achieve a healthy balanced diet.",
     "thumbnail": "https://courses.launchlearning.io/nutrition/veg.png",
     "url": "https://courses.launchlearning.io/nutrition/1.0.1/index_lms.html",
     "activityId": "https://courses.launchlearning.io/nutrition",
     "tags": ["nutrition", "health"],
     "author": {
       "name": "Sara Donald",
       "website": "http://example.com"
     }
   }
 ],

catalogs

The example configuration file has two catalog urls listed. These may be replaced with the url of your own json course definition and additional catalogs may be added. If these are not replaced your Lift installation will display placeholder courses as seen in the Lift demo.

We recommend that if you create a course catalog you also put it in the assets folder and make the URL in the config.json file relative, this will avoid any CORS header issues.

"catalogs": [
  {
    "name": "Default",
    "url": "assets/launch-learning-example-courses.json"
  },
  {
    "name": "Launch Learning",
    "url": "https://courses.launchlearning.io/courses.json"
  }
],

CloudFront Invalidation

If Lift has been installed using the CloudFormation template AWS CloudFront will cache your configuration files. To update your Lift instance immediately navigate to the CloudFront distribution in AWS and create an invalidation for /assets/config.json. You can then view the changes in your browser. You may also have to clear your browser cache.

For more information view the AWS CloufFront Documentation.

Using the Lift demo

The Lift demo site is available for anyone to use. Sign in is available with your Google, Microsoft or Facebook credentials. A user is not created in Lift or Launch LRS, authorisation is handled by the OAuth 2 client.

When you sign in or out an xAPI statement will be sent to our demo Launch LRS. Statements are also sent when adding a course to favourites and for course progress.

Launch Learning cannot provide access to Launch LRS to view statements for privacy reasons. If you wish to see your own statements being sent, the network tab of your browser developer console will show requests as they are sent. For a full demonstration or to see how Lift can be configured for your organisation please contact us.

Google Data Studio xAPI Connector

Fields

A Data Studio field is named according to the xAPI specification. Where a field does not include a path, it is the top-level property and returns a timestamp, UUID or the complete JSON depending on the property. For example: Actor, refers to the Statement Actor and returns the compete Actor JSON.

Statement Count

A count of statements.

Actor

The full JSON of the Statement Actor.

Actor|Agent|Name

Where the Actor is an Agent and a name is defined, it returns the full name of the Agent. An Account name will be returned if no Agent name exists. If neither name exist, an mbox is returned. If none of these exist, N/A is returned.

Actor|Agent|Identifier

Where the Actor is an Agent, returns the Inverse Functional Identifier unique to the Agent in the form mailto:me@example.com.

Actor|Agent|mbox

Where the Actor is an Agent and the Inverse Functional Identifier unique to the Agent is an mbox, returns mbox in the form mailto:me@example.com.

Verb|ID

The Statement Verb ID. For example: http://adlnet.gov/expapi/verbs/launched

Verb|display

The display name of the Verb. Where multiple display names are defined, the first will be returned.

Object

Returns Object ID if the Object is an Activity. Returns Agent Identifier if the Object is an Agent. Returns Sub Statement JSON if the Object is a SubStatement. Returns Object ID if the Object is a StatementRef.

Object|Name

Returns Object Name if defined, where an Object is an Activity. Returns Agent Identifier if the Object is an Agent. Returns Sub Statement JSON if the Object is a SubStatement. Returns Object ID if the Object is a StatementRef.

Result|Success

Returns True, False or Null. Can be used with an Activity ID filter to measure success of a particular quiz or course, or combined with Actor to give individual results.

Result|Completion

Returns True, False or Null. Can be used with an Activity ID filter to measure percentage completion of a course, or combined with Actor to list individual completions.

Result|Score|Raw

The score achieved by the Actor in the experience described by the Statement. This is not modified by any scaling or normalization.

Result|Score|Scaled

The score between -1 and 1 as modified by scaling and/or normalization.

Context

The Statement Context complete JSON.

Context|Registration

The UUID for a registration.

Stored

Date a statement was stored in the LRS

Authority

The full JSON of the Statement Authority.

Authority|Name

Returns Authority Account Name. If no Authority Name exists mbox is returned. If neither exist retruns N/A.

Using default fields in Data Studio

Most Fields are used as a dimension in Data Studio, with Statement as a metric, therefore returning a count of statements for a given Actor, Verb or Object.

Custom fields

Custom fields enable advanced reporting specific to your own data and can be created using the Data Studio Functions

Examples:

Completed date: A Statement stored date based on Verb for courses which do not send a Results>Completion Statement. This can be set in the report to show the minimum or maximum date.

CASE 
    WHEN Verb = "http://adlnet.gov/expapi/verbs/completed" THEN Stored 
END

Start date: A Statement stored date based on Launched. This can then be set in the report to show the minimum date.

CASE 
    WHEN Verb = "http://adlnet.gov/expapi/verbs/launched" THEN Stored 
END

Duration: Time difference between the minimum Start date and minimum Completed date.

DATETIME_DIFF(Min(Completed date), MIN(Start date), HOUR)

Extensions: The Extensions component of the Context JSON extracted using a regular expression. 

REGEXP_EXTRACT(Context, '"extensions":{([^}]+)')

Filtering data

Filters can be created in data studio using any of the default or custom fields. Multiple clauses can be combined using the or function. Combining clauses using the and function is not supported; however, multiple filters may be applied to the same chart to create the same logic.

For example: A filter can be created to include a statement with a Verb containing Passed or a Verb containing Failed. Only data from statements which include either of these verbs will be shown in a chart with this filter. To limit data to a specific course, a second filter can be created to include the relevant object ID. This can then be applied to the same chart.