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 and they will add on the resource they want to interact with.

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. You can find a good explanation of these different mechanisms in the Engine documentation.

Example: Retrieving statements

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

For example, let's say you wanted to let one of your customer's retrieve their statements from the LRS in Engine.

First, make sure you have provided them with a suitable credential (id and secret). If you want them to be able to retrieve all statements from their tenant in Engine, then you'd make sure the credential was created for that tenant, and has the READONLY permission.

Next, you'd provide them with the endpoint to use for requesting the statements. This would something like:{tenant}/statements

This 'statements' endpoint is defined by the xAPI specification. It has a number of parameters allowed to filter and format what is returned by the LRS. You can check out what is possible here in the spec.

Oftentimes using the 'since' parameter is useful for systems polling for new statements that have been added since the last retrieval. You might also filter by 'activityId' to retrieve only statements generated for a particular course (make sure to also pass the 'related_activities=true' parameter as well).

One important note about this request: it must include the X-Experience-API-Version header. Usually it would be passed with a value like this: X-Experience-API-Version: 1.0.0. If you don't pass this header, Engine will assume a version of '0.95', and will return only statements of that version, which most likely none are (it's very old).

Once this request is made, it will return a JSON object like this:

    "statements": [ array of statement objects],
    "more": "/RusticiEngine/lrs/customerA/statements?continueToken=8cf888e8-d5a7-4a7f-a622-51d4bffdecda"

Engine will batch the results it returns so that we're not streaming out millions of statements in one response. The 'more' property there will be a url to use in getting the rest of the results, if there are more. You would replace your original request url with the one in the 'more' property, and keep doing that until the results contain an empty string value for 'more'.

The statements resource in the LRS is primarily meant for streaming out statements to external systems, and doesn't not have fine-grained querying capabilities. For an external system to do that, will have to process the statements after retrieving them.

Hopefully, this gives you enough information to get started in allowing external access to the LRS in Engine!




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