xAPI Integration

Overview

LearningBuilder supports requests using the xAPI (Experience API) format.  The xAPI is supported at Experience API and the specification is defined here. Each configuration will have its own requirements but the basic structure will remain the same.

Transport Options

LearningBuilder supports xAPI Document delivery in the form of REST calls.  If the xAPI feature is enabled, xAPI documents can be delivered directly to Learning Builder through the /API/XAPI/Post endpoint. This endpoint uses the same authentication process that the other public endpoints use. 

Alternatively, LearningBuilder will accept requests through a RabbitMQ queue.  This approach is recommended because it can handle a much higher level of throughput than the website can manage itself.

RabbitMQ provides a couple options for making a connection.

1. AMQP protocol - provides a means to keep an open connection.

2. REST protocol - uses Basic authentication over TLS. The xAPI Document needs to be serialized and added to the payload attribute.

When using the REST HTTP API, use the following structure to wrap the xAPIDocument. When using AMQP, the payload does not need to be wrapped.

xAPI Document

Below, is a sample xAPI Document

Both a defined xAPI Handler and xAPI Verb are required for processing.  Depending on the xAPI Handler, additional parameters may be required.  

Validation Levels

Authentication - Authentication happens real time.  An xAPI document cannot be delivered without successfully completing authentication

1. Valid Payload Format - A valid xAPI document needs to be a well-formed json document with three primary nodes (actor, verb, and object).  At minimum, the verb node needs to have a valid verb and the object node needs to have a valid xAPIHander to identify what action to perform. When making a direct call to LearningBuilder, the sender can get immediate feedback. Otherwise, RabbitMQ will determine the validity of the document out of process.

2. Valid Payload for xAPI Handler -  Each xAPI Handler has its own set of requirements that go beyond the initial structure. Undefined attributes will be ignored by the handler

   • Defines the acceptable verbs

   • Identifies additional attributes required in the payload

   • Identifies the data format required for all of the parameters

3. Valid xAPI request - After the payload is determined to be complete, the request can be processed against the identified object.  However, processing may fail if the target object is not is an acceptable state. This processing is done out of process. So the sender will be unaware if the processing was successful.

Remediation

Any unprocessed xAPI document will remain in a queue to be reconciled manually. Reconciliation could require changes to the xAPI handler if it does not accurately reflect the task.  It may require fixing the target object by putting it into the correct state.

LearningBuilder will not require a resubmission unless the data within the xAPI document is incomplete.