Reports API Initialization

This article details the properties that are passed as parameters to the window.LearnosityReports.init() method to initialize Reports API.

This method is the starting point to initializing and rendering Reports API, and as you can see in the example below, takes two key parameters:

Only the Initialization object is mandatory. Further detail on getting started and initializing Reports API can also be found in the Quick Start guide.

const initializationObject = {
    "security": {
        "consumer_key": "INSERT_CONSUMER_KEY_HERE",
        "domain": "my.domain.com",
        "timestamp": "20120202-1234",
        "signature": "SHA256-HASH - See Security",
        "user_id": "Optional - Needed for Live Activity reports"
    },
    "request": {
        "user_id": "aeee19fb-4e7b-435c-92f9-d93a1099988b",
        "reports": [
           {
               ...
            },
            {
               ....
            }
        ],
        "label_bundle": {
            "activity": "Activity",
        },
        "configuration": {
            "questionsApiVersion": "v2", // use a specific version of Questions API
            "itemsApiVersion": "v1" // use a specific version of Items API
        }
    }
}

const callbacks = {
    errorListener: function (e) {
        // Adds a listener to all error codes.
        console.log("Error Code ", e.code);
        console.log("Error Message ", e.msg);
        console.log("Error Detail ", e.detail);
    },
    readyListener: function () {
        console.log("Learnosity Reports API is ready");
    }
};

const reportsApp = window.LearnosityReports.init(initializationObject, callbacks);

Initialization Object

The Initialization object is a JSON object which is passed as the first parameter into the window.LearnosityReports.init() method. It includes all the information needed to initialize the API.

It contains the following two top-level properties:

The Security object is a property generated by the Learnosity serverside SDKs to ensure that any of the APIs are only initialized from a secured, allowed source, using your consumer key and secret.

This is handled by our SDKs in:

For other languages, please see our Security & Authentication page on how to sign your requests.

The Request object contains all of the configuration properties for which reports to load, where to load them, and any optional configuration properties

Only a few properties are mandatory, the rest provide a high level of customization to enable you to tailor the reporting experience to suit your needs.

Properties

= mandatory property

  • reports array[ReportObject]

    Defines the reports to be rendered and their configuration.

  • configuration object

    Configure options relating to your chosen reports and the behavior of Reports API.

  • label_bundle object

    An object containing custom labels to be used in the reports.

  • user_id string

    Set a default user ID to apply to each report.

The Callbacks object contains optional callback functions that allow detection of the 'ready' status of an Reports API instance and any errors encountered.

An example of how to construct this object can be seen above.

The readyListener callback in particular is very important for the correct functioning of Reports API. most of the methods provided by the returned object from window.LearnosityReports.init() will not be fully available until after the readyListener callback has triggered.

Properties

  • cutScoreMutator function

    Manipulates or mutates the score values before the following reports are rendered on the page: last score by Item by user and last score by Activity by user.

  • dataListener function

    This function is called when all report data has been loaded.

  • displayNameListener function

    Maps raw names and identifiers in the report data to user friendly display names at runtime.

  • errorListener function

    This function is called when one of the preset Learnosity API errors are thrown.

  • readyListener function

    This function is called when the API has been successfully initialized.

  • scoreMutator function

    Callback function used in the learning outcomes report to mutate scores shown in each cell of the report.