Reporting
xAPI defines a query API that is used to get statements out of a Learning Record Store (LRS). This API is primarily designed for the transfer of statements between LRSs, though it can be used for simple reporting. It’s envisaged that for more complex queries and reporting, systems will fetch all relevant statements from the LRS and then store and aggregate them in an appropriate format for reporting.
Simple reporting
The xAPI specification defines a method to fetch statements from an LRS. This method is called GET Statements. For simple reporting, it is possible to build a UI that calls this API directly and displays the data. This approach is not recommended for more complex reporting and analytics.
GET Statements allows a single statement to be fetched by statement id, with a special parameter ‘voidedStatementId’ that must be used if the required statement has been voided. Groups of statements can be fetched filtered by agent, verb, activity, registration and time period (using ‘since’ and ‘until’). No other filters are possible, so the query API is not appropriate if you require other filters (see below for other options).
Other parameters are not filters exactly, but affect what is returned by the LRS:
- ‘related_activities’ and ‘related_agents’ flags determine how the agent and activity filters are applied. If these flags are set to true, the LRS will match statements where the agent or activity appears anywhere in the statement, not just within the actor and object.
- ‘limit’ determines the maximum number of statements the LRS will return in a batch. The LRS itself may also apply a limit. If more statements are found than the limit, the LRS will provide a URL that can be requested to fetch the next batch of statements (see ‘more’ below).
- ‘attachments’ – whether or not the LRS should send any attached files with the statements. Most statements don’t include file attachments, but attachments can be very large so don’t request them unless you need them.
- ‘ascending’ – normally the LRS will return the oldest statements first as this is most useful for LRSs pulling statements from each other. If you want to fetch the newest statements first, set the ascending flag to true.
- ‘format’ – what human readable names and descriptions are included in the statements (see below).
The ‘format’ parameter determines what data is included in the statements returned. ‘exact’ format returns the statements exactly as they were received by the LRS (with some possible exceptions). ‘exact’ format should be used when moving statements between LRSs or other systems that store statements. The ‘ids’ format returns only ids are returned with none of the human readable descriptions. This is useful if you need to fetch data that will be used for aggregation or other processing where human language names and descriptions are not required.
The ‘canonical’ format requests the LRS to return its own internal definitions of objects, rather than those provided in the statement. If you trust the LRS, this is normally the most appropriate format when the data will be displayed to the end user. The LRS will build its internal definitions of objects based on statements it receives and other authoritative sources.
Having retrieved the statements, you may need to process and aggregate the data before displaying it to the user. The prototypes include a report sample which does this processing in JavaScript on the user’s computer. This sort of processing is ok for simple reports, but for anything more advanced you should consider the other options below.
Additional reporting APIs
Some Learning Record Stores have additional reporting APIs beyond what is required by the specification. The scope and function of these APIs varies between products, but it’s possible that the LRS you’re using provides sufficient functionality to support the reports you need.
The main disadvantage of using these additional APIs is that they are not standardized across different LRSs. Any reporting solution you build using these APIs will be tied to a particular LRS. You can still fetch statements into this LRS from other LRSs and then pull them on into your reports, but you will not be able to use your reporting system directly with another LRS without some custom integration work.
The xAPI specification working group have discussed creating an additional Reporting API specification as an optional extra for LRSs that want to provide additional reporting APIs. As with anything, this requires an investment of effort in order to happen. Contact us if you’d like to help spearhead that effort.
Complex reporting and analytics tools
The approach we recommend for serious reporting and analytics is to have a product which fetches all relevant statements from the LRS and store them in it’s own database. Data can then be processed server-side, ready to be quickly delivered to the user.
The advantage of this approach is that the reporting and analytics tool has full control of the data. It can store and process the data as it sees fit in order to provide the fastest response to users. There are no limits to the kinds of queries that can be made of the data.
Transfer of statements between the LRS and the reporting or analytics platform could be either a push or a pull. Either the LRS could be configured to forward statements on, or the analytics platform could be set up to pull statements. See sharing statements between LRSs.
Get in touch.
An LRS provides actionable insights from your training and performance data. It generates powerful and stunning reports from your xAPI data.