What is the cmi5 Fetch Parameter? End the confusion

Learn about the cmi5 fetch parameter. The cmi5 specification calls for a “fetch” parameter to be added to the launch URL when opening and Assignable Unit (AU). What is the cmi5 fetch parameter? How is it used? Are there any “gotchas”? In this article I will attempt to end the confusion.

Author’s Note: This is a technical article aimed at content tool developers, or those that are creating cmi5 AU by hand.

What is the fetch Parameter?

The cmi5 fetch parameter is a URL that must be called by the AU. The fetch URL must be used by the AU to get an authorization token. This token is then placed in the Authorization header for all HTTP requests made to the xAPI endpoint. In other words, an AU’s authorization to write to the Learning Record Store (LRS) is via the token retrieved from the fetch URL.

The fetch Parameter Rules

There just a few rules around the fetch parameter:

  1. The AU may call the URL only ONCE per session. Subsequent calls to the URL by the AU will receive an error.
  2. The rule above indicates the LMS must generate a unique fetch URL for each launch of an AU.

The Gotcha

There is an obvious “gotcha” in rule number 1 above. What if the user refreshes their browser in the middle of an AU? If the content is unprepared for this event, it will attempt to call the fetch URL again, get an error and likely display that error to the user. At this point the user is basically dead in the water because the AU has lost authorization to write to the LRS.

There is a simple solution for this and it is called “sessionStorage.” All major browsers support the ability to store data locally with the sessionStorage object. Here is a simple script, using jquery, to first check if the required token exists in sessionStorage, and if not then go ahead and get it from the fetch URL (Warning, code ahead).

$(function() {
    // First, Read the fetch url parameters
    var fetchUrl = parse("fetch");

    // Next, check if this value exists in sessionStorage.
    var token = sessionStorage.getItem(fetchUrl);

    // Was the token found in sessionStorage?
    if (!token) {
        // Call the fetch url to get the token
        $.post(fetchUrl, null, function(t) {
           token = t["auth-token"];

          // Save the token to sessionStorage
          sessionStorage.setItem(fetchUrl, token);

        }, "json");

Why does this work? The fetch parameter is passed on AU launch URL. If the browser is refreshed, the fetch parameter is unchanged. So we use the fetch URL as the “name” property in our call to sessionStorage.setItem(). Then, if the browser is refreshed we can easily find the previously obtained authorization token with a call to sessionStorage.getItem().

For more information on cmi5, be sure and check out this blog’s xAPI and cmi5 category.


Art Werkenthin
Art Werkenthin is president of RISC, Inc. and has over 30 years' experience working with LMS systems in the Oil & Gas, Retail, Finance and other industries. Mr. Werkenthin holds a B.S. in Electrical Engineering and an M.B.A. in Information Systems Management from the University of Texas. Mr. Werkenthin is a member of the ADL cmi5 committee and frequently presents on cmi5 and xAPI. Follow him on Twitter @AWerkenthin for xAPI and cmi5 updates, as well as blog post announcements.