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

Array[Report]
An array of configuration objects for each report being initialized.
object

An object containing custom configuration options for the Reports API.

Properties:
questionsApiVersion
Type: string

Deprecated Reports API automatically sets the required Questions API version. No longer has any effect.

Originally, this option specified a version of Questions API to use for reports that rendered Questions, before LTS versions were introduced.

Example: "v2"
itemsApiVersion
Type: string

Deprecated Reports API automatically sets the required Items API version. No longer has any effect.

Originally, this option specified a version of Items API to use for reports that rendered Items, before LTS versions were introduced.

Example: "v1"
object
An object containing custom labels to be used in the reports.
Properties:
a_problem_occured
Type: string

Default: "A problem occurred. Please try again later. If the problem persists contact your administrator."

activity
Type: string

Default: "Activity"

attempted
Type: string

Default: "Attempted"

not_attempted
Type: string

Default: "Unattempted"

not_marked
Type: string

Default: "Not marked"

partial
Type: string

Default: "Partially correct"

correct
Type: string

Default: "Correct"

incorrect
Type: string

Default: "Incorrect"

incomplete
Type: string

Default: "Incomplete"

seen
Type: string

Default: "Seen"

date
Type: string

Default: "Date"

items
Type: string

Default: "Items"

total_n_of_items
Type: string

Default: "Total # of items"

last_item_n
Type: string

Default: "Current Item #"

n_of_items_correct
Type: string

Default: "# of items correct"

n_of_items_incorrect
Type: string

Default: "# of items incorrect"

n_of_items_skipped
Type: string

Default: "# of items skipped"

n_of_items_not_marked
Type: string

Default: "# of items not marked"

of_items_have_been_seen
Type: string

Default: "of items have been seen"

of_items_were_answered_correctly
Type: string

Default: "of items were answered correctly"

of_items_were_attempted
Type: string

Default: "of items were attempted"

of_score_was_answered_correctly
Type: string

Default: "of the total score was answered correctly"

of_questions_have_been_seen
Type: string

Default: "of questions have been seen"

total_n_of_questions
Type: string

Default: "Total # of questions"

n_of_questions_correct
Type: string

Default: "# of questions correct"

n_of_questions_incorrect
Type: string

Default: "# of questions incorrect"

n_of_questions_skipped
Type: string

Default: "# of questions skipped"

n_of_questions_not_marked
Type: string

Default: "# of questions not marked"

of_questions_were_answered_correctly
Type: string

Default: "of questions were answered correctly"

of_questions_were_attempted
Type: string

Default: "of questions were attempted"

time_spent
Type: string

Default: "Time spent"

total_time_spent
Type: string

Default: "Total time spent"

total
Type: string

Default: "Total"

progress
Type: string

Default: "Progress"

question
Type: string

Default: "Question"

item
Type: string

Default: "Item"

score
Type: string

Default: "Score"

items_correct
Type: string

Default: "Items Correct"

user
Type: string

Default: "Student"

users
Type: string

Default: "Students"

paused
Type: string

Default: "Paused"

completed
Type: string

Default: "Completed"

in_progress
Type: string

Default: "In progress"

not_started
Type: string

Default: "Not started"

saved
Type: string

Default: "Saved"

suspended
Type: string

Default: "Suspended"

discarded
Type: string

Default: "Discarded"

msg_no_data
Type: string

Default: "There is no data for this report."

status
Type: string

Default: "Status"

active
Type: string

Default: "Active"

focuse
Type: string

Default: "Active"

unfocused
Type: string

Default: "Away"

pause
Type: string

Default: "Pause"

pause_confirmation
Type: string

Default: "This action saves answers for the following student(s), but won't let the student(s) continue until you resume the test. Are you sure you want to do this?"

unpause
Type: string

Default: "Unpause"

unpause_confirmation
Type: string

Default: "This action lets the following student(s) continue the test. Are you sure you want to do this?"

extend_time
Type: string

Default: "Extend Time"

extend_time_confirmation
Type: string

Default: "This action extends the time left for the following student(s). Are you sure you want to do this?"

save_quit
Type: string

Default: "Exit & Save"

save_quit_confirmation
Type: string

Default: "This action saves answers for the following student(s) and closes the test. Are you sure you want to do this?"

exit_discard
Type: string

Default: "Exit & Discard"

exit_discard_confirmation
Type: string

Default: "This action discards answers for the following student(s) and exits the test. Are you sure you want to do this?"

confirm
Type: string

Default: "Confirm"

continue
Type: string

Default: "Continue"

confirmation_heading_action
Type: string

Default: "Confirm Action"

cancel
Type: string

Default: "Cancel"

group_name
Type: string

Default: "Group Name"

group_count
Type: string

Default: "Group Count"

lowest_score
Type: string

Default: "Lowest Score"

highest_score
Type: string

Default: "Highest Score"

mean_seen_activities
Type: string

Default: "Average Seen"

mean_attempted_percent
Type: string

Default: "Average Attempted (%)"

mean_score
Type: string

Default: "Average Score"

median_score
Type: string

Default: "Median Score"

stddev_score
Type: string

Default: "Standard Deviation"

lowest_percent
Type: string

Default: "Lowest Score (%)"

highest_percent
Type: string

Default: "Highest Score (%)"

mean_percent
Type: string

Default: "Average Score (%)"

median_percent
Type: string

Default: "Median Score (%)"

stddev_percent
Type: string

Default: "Standard Deviation (%)"

population
Type: string

Default: "Population"

hour
Type: string

Default: "hour(s)"

minute
Type: string

Default: "minute(s)"

second
Type: string

Default: "second(s)"

hr
Type: string

Default: "hr(s)"

min
Type: string

Default: "min(s)"

sec
Type: string

Default: "sec(s)"

string

A default user ID to apply to each report in the reports array that does not specify a user ID, when the type of report expects a user ID to be specified.

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

Function to be called on a Learnosity error event. Receives an Error object.

See troubleshooting for more information.

Parameters
error
Type: Error
Function to be called when the API has been successfully initialised.
Function to be called when all report data has been loaded.
Parameters
data
Type: array[reportDataObject]

Callback function used in some reports (notably, aggregate reports) to map raw names and identifiers in the report data to friendly display names at runtime.

This function is called whenever there are 1 or more raw values used in the report that can be replaced, with the list of raw values (in no particular order) given as the only argument. The return value should be an array of replacement names corresponding to each raw value.

Parameters
originalNames
Type: array[String]

A list of raw names/values in the report that can be remapped for display using this callback; e.g. ["school_1", "school_2", "school_3"]. The possible values varies depending on the type of report and the report data.

 
displayNameListener: function (originalNames) {
    // A sample mapping of possible raw data values from the report and their corresponding display names.
    // This example is for an aggregate report, where the group names from the dataset may match the keys below:
    var displayNameMap = {
        "us": "United States",
        "cn": "China",
        "gb": "Great Britain",
        "au": "Australia",
        "us-ma": "Massachusetts",
        "cn-11": "Beijing Municipality",
        "gb-eng": "England",
        "au-nsw": "New South Wales",
        "school_1": "Massachusetts Institute of Technology",
        "school_2": "Peking University",
        "school_3": "University of Oxford",
        "school_4": "University of New South Wales"
        // Include as many display name associations as desired
        // ...
    };

    var displayNames = [];
    for (var i = 0; i < originalNames.length; i++) {
        var originalName = originalNames[i];
        if (originalName in displayNameMap) {
            // The mapped value is what will be displayed instead of the corresponding original name
            displayNames.push(displayNameMap[originalName]);
        } else {
            displayNames.push(originalName);
        }
    }

    return displayNames;
}

Callback function used in the item-scores-by-tag-by-user report to mutate scores shown in each cell of the report.

This function is called before scores are rendered in the report. The scores argument passed to the function is an array of score mutator objects. The score can be mutated using these methods. The return value of scoreMutator is ignored.

Parameters
scores
Type: array[scoreMutatorObject]

An array of objects, each corresponding to a single cell in the report. Each object exposes methods for mutating the score shown in the report. See scoreMutatorObject definition for details of each method.

 
scoreMutator: function (scores) {
    for (var i = 0; i < scores.length; i++) {

        // apply a custom business rule to treat unattempted questions as incorrect
        var unattempted = scores[i].unattempted();
        var incorrect = scores[i].incorrect();

        scores[i].unattempted(0);
        scores[i].incorrect(incorrect + unattempted);

    }
}

In the Initialization object and Callback sections above, there are some object definitions which are complex enough to document separately. These are listed below, and linked from the relevant documentation above.

Objects

object

A configuration object used for the initialization of an individual report. An object of this type must conform to the object definition of one of the available Learnosity report types.

See Report Types reference for more information.

Properties:
id
Type: string
A host-page supplied unique identifier for this report. Used to render the report into a DOM hook on the host page.
type
Type: string
The type of report. Must be a valid report type. 
{
    "id": "report-01",
    "type": "session-detail-by-item",
    "session_id": "123e4567-e89b-12d3-a456-426655440000",
    "user_id": "aeee19fb-4e7b-435c-92f9-d93a1099988b"
}
object

See troubleshooting for more information.

Properties:
code
Type: number
msg
Type: string
detail
Type: string
object
An object containing the id and data for a given report.
Properties:
id
Type: string
A host-page supplied unique identifier for this report. Used to render the report into a DOM hook on the host page.
data
Type: object
an object containing the raw data packet used to generate the report.
object

An object containing methods to mutate a score, as well as assign HTML data attributes to certain elements to make them accessible for design and behavioural changes. The individual correct, incorrect, unattempted and unmarked components of the score are exposed as getters, and each component can be overridden using the corresponding setter methods. The components of the score will be used to render score percentages, score bars and tooltips.

Additional countSeen() and percentScore() methods are also available.

Properties:
countSeen()
Type: function()
Returns the number of items from which this score is calculated, ie. the number of Items presented to the user that meet the filters for this particular report (or cell within the report).
correct()
Type: function()
Returns the correct component of the score.
domData(object)
Type: function()
Used to store custom data attributes against this score's cell, for the purpose of custom logic or CSS selectors. Pass a map of key value pairs which will be stored on the DOM as custom data attributes. Each key will be added to the score's cell as a data attribute of the form data-custom_keyname="value". The data attribute can then be used as a CSS selector for applying custom styles, or a DOM selector to hook your own custom logic to. See an example domData() customization at our Learnosity Demos Learning Outcomes - Class Demo
correct(Number)
Type: function()
Sets the correct component of the score.
incorrect()
Type: function()
Returns the incorrect component of the score.
incorrect(Number)
Type: function()
Sets the incorrect component of the score.
unmarked()
Type: function()
Returns the unmarked component of the score.
unmarked(Number)
Type: function()
Sets the unmarked component of the score.
unattempted()
Type: function()
Returns the unattempted component of the score.
unattempted(Number)
Type: function()
Sets the unattempted component of the score.
percentScore(Number)
Type: function()
Sets the overall percent score. Normally, Learnosity uses correct / maxScore to calculate the percentScore, but this setter can be used to override the displayed percentage regardless of the values of the individual score components.