External Access to Engine's LRS Endpoints


In most cases, a customer's first introduction to xAPI with Engine will be through courses packaged up with a Tin Can manifest (tincan.xml), or the newer cmi5. These course are imported and launched in the same way as any other learning standard in Engine, and the necessary LRS endpoint and authentication credentials are provided to the content automatically.

At some point, however, you may want to move beyond this type of content to working directly with the LRS in Engine. You may, for example, want to allow an external Learning Record Provider to send xAPI statements to Engine to be stored alongside data from your own launched courses. In this type of situation, the learner is doing an activity that is not tied to a course imported or launched from Engine.

You may also have your own internal applications or processes that need to retrieve statements from Engine for analytics or reporting purposes.

To enable an external system to send or retrieve statements from Engine, there are a couple of things you'd need to provide.

Engine's LRS Endpoint

Engine's LRS is accessed at an endpoint that typically looks like the following:

For 2017.1:{tenant}
For 2018.1 (and above):{tenant}

That is the base LRS endpoint. Content and tools will hit various resources on that endpoint (/statements or /state, etc.). But typically you'd provide just this part of it to external tools.

If you are not using Engine's built-in multi-tenant capabilities, then the {tenant} in the url would be "default". Otherwise, you'd need to use the appropriate tenant name for where you want to save the data.

Setting up Credentials

You'll also have to configure some credentials for the tool/provider to use to access the endpoint. There are several ways to do this in Engine.

The simplest way to do this is by using the xAPIBasicAccounts setting in your Engine config file. You may see a commented out sample of this in the file included in the release.

Entries are each on a single line (or comma-delimited) and take the form of: 

user1 : password1 : role
user2 : password2 : role 

The role section here (and in other places) would typically either be "user", which lets the user read/write data created by itself (good for an external LRP), or "read-only", if you have a system that's just going to be pulling statements out. You may also have a single "root" account for your administrative usage.

For API integration customers, though, the better route for setting up credentials is to use the xapiCredentials resource in the REST API to do this, as it gives you an easier mechanism for managing them.

One thing to note with that resource: the API does not use the words 'username' and 'password' -- instead the corresponding values are 'xapiCredentialsId' and 'secret'.

You will basically do a PUT (if you want to set the xapiCredentialsId), or POST (if you want us to generate one) to that resource with the following details for the credential:

  • name: a descriptive name for the credentials (since the id may not be recognizable)
  • xapiCredentialsAuthType: BASICAUTH is the value for this to be used as a Basic Auth credentials in a request
  • secret: this is the password for this credential
  • permissionsLevel: there are four options for this (similar to the roles mentioned earlier)
    • USER - Can read/write any data created by this set of credentials. This is most likely what you'd need to use for most LRPs.
    • ROOT - Can read or write any data in the LRS. Probably not something you use for most cases.
    • READONLY - Can only read information from the LRS, but is not limited to statements created by this set of credentials.
    • WRITEONLY - Can only write information to the LRS

For more complicated auth scenarios, there is also an alternative to setting/storing credentials in Engine, which is through using our xAPI Authorization Callback mechanism. With that, you are basically telling Engine to hit an endpoint on your side to validate the auth information passed to us with xAPI requests. If that sounds like something you need, get in touch with us and we'll walk you through it.

Now, with the credentials created, and the endpoint information, you should have what you need to allow another tool to access your statements!

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request


Powered by Zendesk