INSERTING STATEMENTS GUIDE
To quickly try out inserting statements into your Learning Locker instance you can use Postman. Postman is a tool for creating and sending HTTP requests. You can download and install Postman via their website. Once you’ve installed Postman, you can check out the documentation for our xAPI HTTP Interface.
Before you start designing and inserting your own statements in production, you should consider using tools that already transmit xAPI statements. If you can’t use any of these existing tools, there are a number of processes and best practices that you can follow to fall into the pit of success when designing and transmitting your own statements.
Design Statements
List the experiences you wish to capture for analysis.
Create a recipe (a statement template for an experience) for each experience from the previous step.
Map the variables in each recipe to variables in your application.
Transmit Statements
Identify the sources that will construct and transmit statements.
Implement the transmission from the sources to the LRS.
LIST EXPERIENCES
At this stage you should figure out which experiences are important to track (e.g. logging in, completing a quiz, watching a video, etc.) and what data you ideally need to capture for analysis (e.g. quiz score, video duration, etc.). When creating this list, you may wish to consider the data required to:
Answer your research questions.
Produce your stakeholder reports.
Adapt and improve the experiences of your users.
CREATE RECIPES
At this stage you should create some example statements for each of the experiences you listed earlier ensuring that you include all of the data required for each experience inside the statement.
...
There are more example statements provided in the xAPI specification. For further support and consultation, you can email hello@learninglocker.net.
MAP VARIABLES
Using the recipes from the previous step, you should map the data required in each of the recipes to variables in your application. You might find it useful to use a table like the one below.
Statement Property | Mapping |
---|---|
| User’s full name from our user data model. |
| The URL of the application: “http://www.example.org” |
| User’s identifier from our user data model. |
| The URL of the application: “http://www.example.org” |
… | … |
IDENTIFY SOURCES
At this stage, you should identify where the statement will be constructed and transmitted for each recipe that you identified earlier.
You should consider whether you will be sending statements from the client-side or the server-side for each recipe as this will affect the transmission implementation. Alternatively, you may be creating statements using an external service, so at this stage you may also wish to consider whether you will need to poll that service for events or whether you can use webhooks or an event listener (with something like Redis).
IMPLEMENTING TRANSMISSION
At this stage, you can start planning and implementing the transmission of statements to your Learning Locker instance via the xAPI HTTP Interface. However, there are a number of things listed below that you should consider before you begin.
BATCHING STATEMENTS
If you’re potentially sending a significant number of statements in a short period of time, you should consider sending statements to the LRS in batches to improve response times, reduce HTTP requests, and reduce the elapsed time spent sending statements. For example, on the server-side this may be implemented with the use of a statement log and a cron job (the Moodle Logstore plugin is an example of this).
HANDLING SENDING FAILURES
If a statement fails to be sent you may want to consider implementing some retry strategies to resend statements that previously failed to be stored (normally because of downtime). We’d recommend that you send these failed statements in batches. If you’re sending statements from the client-side, we’d recommend that you wait 5-60 seconds between retries and retry a maximum of 3-5 times. If you’re sending statements server-side, you may want to consider storing failed statements somewhere and using a Cron job to send them.
SENDING SECURELY
If you’re sending statements from the server-side this shouldn’t be an issue as the LRS credentials are not exposed. However, if you’re sending statements from the client-side, you should consider finding a way to protect the LRS credentials so that they’re not exposed to tech-savvy users, since a malicious user may try to read sensitive data from, or write unwanted data to, the LRS. We’d recommend using the xAPI launch process with Learning Locker’s Launchr, you can email hello@learninglocker.net for more information about this.