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": "43466577",
        "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 PHP, Java, Python, Ruby or C#. 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
A specific version of Questions API to use for reports that render Questions.
Example: "v2"
itemsApiVersion
Type: string
A specific version of Items API to use for reports that render Items.
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: "Not attempted"
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": "demo_student"
}
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. 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.
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.