Introduction
The xAPI (formerly Tin Can API) API is an e-learning software specification. This type of software allows learning content and learning systems to speak to each other in a way that records all types of learning experiences, which are then recorded in a Learning Record Store (LRS). An LRS can exist within traditional Learning Management Systems, or on its own.
Requirements and limitations
- Docebo supports the Tin Can Standard 1.0.
- The maximum file size is 2 GB.
- The xAPI (Tin Can API) content must be uploaded as a ZIP package.
- Docebo LRS works in pairs with the Docebo platform, to be able to link activities completed by the users to course progress, they are required to recognize the activity ID passed in the xAPI statement. To make the LRS recognize these activity IDs, upload xAPI packages with a proper tincan.xml descriptor in them.
- You can upload xAPI/TinCan content into e-learning, Instructor-Led Training (ILT) and Virtual Instructor-Led Training (VILT) courses.
Uploading xAPI packages
You can upload an xAPI package from your device, or you can do so from an external link. We recommend uploading xAPI packages from the Training material page, where you can reuse them across multiple courses. You can also upload xAPI packages directly from within a course: see Uploading xAPI files from within a course.
Uploading xAPI files from the Training materials page
To access the Training material page, log in as a Superadmin or Power User, open the Navigation menu under the Content and delivery (folder icon), and click Training materials.
In the left panel, select the folder where you want to upload the files, then click the + New button. The dropdown shows two options for xAPI:
- xAPI from file: upload one or more xAPI packages from your device, following the steps below.
- xAPI from URL: link an xAPI package via an external URL. See Linking xAPI content as training material for instructions.
You can also start this upload from the Content center: open the Navigation menu, then in the Content and delivery (folder icon), click Content center. Click the + New button and select xAPI from file.
To upload xAPI files from your device:
- Select up to 20 ZIP files to upload. Each file can be up to 2 GB in size.
- If you are uploading from the Content center, select the destination folder from the right panel.
- Once the upload starts, a panel appears in the top-right corner of the screen. If you close it, you can reopen it by clicking the cloud icon (Uploads) in the top-right corner. The panel shows real-time status for each file.
- You can navigate freely within the platform while uploads are in progress. Note that refreshing the page or closing the tab will interrupt all in-progress uploads. The browser displays a pop-up confirmation before you leave the page.
- To cancel a specific upload, click the X next to that file in the panel. To cancel all in-progress uploads, click Cancel in the panel.
- Once the upload is complete, you can click the file name to go to the training material's edit page, or click the folder icon to navigate to the folder where the file was saved.
Uploading xAPI files from within a course
While you can upload xAPI packages directly within a course, we recommend using the Training material page instead, as it supports bulk upload and reuse across multiple courses.
From the Navigation menu under the Content and delivery (folder icon), find the Courses item. Look for the course for which you would like to upload the xAPI training material and click on its description, then move to the Training material tab.
From here, click Add training material, then select xAPI (Tin Can) from the dropdown menu.
The upload page has three tabs: xAPI (Tin Can), Additional Info, and Enhanced Security. In the Tin Can tab, select Upload File to choose the xAPI (Tin Can API) file from your device and set whether you want to track all activities in the package. If checked (this is the default setting), the platform will track all activities, including activities and sub-activities. In this way, when completing the first module of the Tin Can training material (considering that a Tin Can training material is composed of multiple modules), the entire Tin Can is marked as completed. If the Track all activities option is not selected, only the main activities of the package will be tracked, and all modules have to be completed for the Tin Can to be marked as completed.
The platform identifies Tin Can content as completed when learners press the Close button (also named Exit or Submit). Failing to press this button may result in the learning progress not being sent from the Tin Can package to the platform and in the Tin Can content not being marked as completed. For this reason, it is highly suggested to include a completion screen in your Tin Can packages to be displayed when the Tin Can package confirms that tracking data has been transferred and to show the Close button on this screen.
While the file is uploading, move to the Additional info tab to fill in a short description for your file and select a thumbnail. You can also change the title or the thumbnail of the training material later.
You can also add tags to your training material to improve its searchability in your platform’s global search. If the auto-tagging feature is enabled in your platform, some tags may be automatically generated based on the content of your training material, as understood by your platform using artificial intelligence. Auto-tagging relies on the platform’s ability to extract text or generate a transcript. See the complete list of supported content types for text extraction and transcript generation. You can edit or remove tags at any time, with a limit of 15 tags per training material.
Please note: The auto-tagging feature may encounter problems when processing xAPI training material created through the use of certain authoring tools embedding textual contents directly into programming files, and compressing images so that their quality does not allow Optical Character Recognition (OCR). We are currently working to confront this limitation by collaborating with some of the major authoring tools providers.
When you're finished, press Save changes. If the file format is correct, the xAPI package will be uploaded as course material, and a message will be displayed on the top left of your screen.
After the upload is complete, you will land on the Training material tab. Click the menu icon at the end of the xAPI training material row, then select Settings to configure the training material. When setting the View mode, please note that Theater mode prevents learners from using their microphones. If your xAPI content requires microphone access, we recommend selecting Play in new window instead.
Linking xAPI content as training material
As an option to upload xAPI content from your device, you can link it from an external URL. As a first step, you must create a predefined list of source URLs on the platform. This step ensures that the platform can play the content for learners. To do so, access the Navigation menu, find the Configuration (spanner icon), click on Platform setup and tools, then select the Advanced settings option from the Settings section. Then, move to the E-learning tab.
Move to the xAPI (Tin Can) external content field and add the training material URL in the corresponding text field. You can add up to 20 URLs.
To support additional URLs, use a wildcard domain. For example, enter http://www.domain.com/* without specifying the content file name or extension, and include an asterisk (*) at the end of the URL. When adding training material to a course, you can then specify the file name and extension individually (e.g., file_name_1.zip after the domain). Please note that wildcard domains must be added manually, it is not possible to add them via API.
By using this method, the domain you entered will count as one of the 20 allowed URLs, but you will be able to add more than 20 pieces of xAPI external content.
Click Add to confirm the domain, it will be listed under the input field.
To add a salt secret to a URL, click the lock icon at the end of the URL row. Then, enter and confirm the salt secret, and press the checkmark.
If you do not add a salt secret, the third party will treat the content like any other xAPI content launched from your platform. Adding a salt secret, however, generates a checksum that validates the content's launch, allowing the third party to confirm the content's authenticity.
When finished, press Save.
Once you have set up the source URLs, navigate to the Training material page. In the left panel, select the folder where you want to add the content, then click the + New button and select xAPI from URL. You can also do this from the Content center. In this case, you will have to select the destination folder in the slide-out panel.
On the upload page, choose the From URL option, then select a URL from the Select URL dropdown menu, which will display all the URLs you added in the previous step.
If you select a wildcard domain that does not include the name and extension of the file, the Additional path field will appear under the Select URL field so that you can insert the name and the extension of the training material.
Please note: You can add the folder or the subfolder in which your file is located either in the Select URL field or in the Additional path field, giving you considerable flexibility when uploading xAPI training material.
Enter a title and description for the content in the corresponding text fields. Next, decide whether you want to track all activities in the package. If you enable this option (which is the default setting), the platform will track all activities and sub-activities. If you disable it, only the main activities of the package will be tracked.
Move to the Additional info tab and optionally set a short description for the content and select a thumbnail. You can also add tags to your training material to improve its searchability in your platform’s global search. If the auto-tagging feature is enabled in your platform, some tags may be automatically generated based on the content of your training material, as understood by your platform using artificial intelligence. Auto-tagging relies on the platform’s ability to extract text or generate a transcript. See the complete list of supported content types for text extraction and transcript generation. You can edit or remove tags at any time, with a limit of 15 tags per training material.
Finally, move to the Enhanced security tab where you can set to add an OAuth code to the launch URL, and then select the OAuth client from the corresponding dropdown menu. Click Save changes to create the training material.
You can also link xAPI content from within a course: navigate to the Training material tab of the relevant course, click Add training material, select xAPI (Tin Can), then choose the From URL option and follow the same steps from selecting a URL onwards.
Managing the settings of the training material
Once the training material has been uploaded, you can manage its settings as described in the article Managing training material settings and prerequisites.
Best practices
-
If you want to track your xAPI (Tin Can) package remotely, you need to upload the package directly into your platform. Your Docebo platform does not support completely anonymous tracking. If you want to send xAPI (Tin Can) statements to our platform, you can do so using the following link format:
https://www.lmsaddress.com/tcapi/. Additionally, users must have a valid email address associated with their account for the platform to store tracking data for xAPI training materials. - We recommend uploading and managing your xAPI training materials from the Training material page, where you can upload multiple files at once and reuse them across multiple courses.