Methods

This article details methods the host page can use to interact with Reports API.

The following methods are accessed via the window.LearnosityReports object.

When the <script src="https://reports-va.learnosity.com"></script> tag is included on the page, the window.LearnosityReports object is instantiated, and ready for use.

LearnosityReports.init() method initializes Reports API and returns an instance of the application object (ReportsApp). This instance needs to be saved locally for future access to initialized reports.

Parameters
initObject
Type: object

See the Reports API initialization object for more information.

callbacks
Type: object

See the Reports API events during initialization for more information.

Returns: reportsApp

The following methods are accessed via the reportsApp object returned by window.LearnosityReports.init(). This object provides methods to interact with, and receive information relating to the reports placed on page.

ReportsApp.getReport() returns a Report object used for interacting with an initialized report, based on the id of the report provided in the request object.

Parameters
reportId
Type: string

The report ID provided in the request object when calling the LearnosityReports.init() method.
Returns: report

The following methods are accessed via the report object returned by reportsApp.getReport(). This object provides methods to interact with, and receive information for reports used.

Binds a callback function that will be invoked whenever the eventName is triggered.

Parameters
eventName
Type: string
Name of the event that you want to stop listening to

See Report specific events for more information.

eventCallback
Type: callback()
If no callback is provided, all event handlers for the eventName will be removed.

Subscribe to and control additional user IDs.

Important Only applicable to the live-activity-status-by-user report.

Parameters
userArray
Type: array[userObject]
Array of users to be added to the report.

Discard and terminate the test for the user IDs provided.

Important Only applicable to the live-activity-status-by-user report.

Parameters
userArray
Type: array[string]
Array of user_ids to be added to the report.

Save and terminate the test for the user IDs provided.

Important Only applicable to the live-activity-status-by-user report.

Parameters
userArray
Type: array[string]
Array of user_ids to be added to the report.

Submit and then exit the test for the user IDs provided.

Important Only applicable to the live-activity-status-by-user report.

Parameters
userArray
Type: array[string]
Array of user_ids to be added to the report.

Extend time (in seconds) for the test of the user IDs provided.

Important Only applicable to the live-activity-status-by-user report.

Parameters
userArray
Type: array[string]
Array of user_ids to be added to the report.
seconds
Type: number
number of seconds to extend the assessment timer by

Pause the test for the user IDs provided.

Important Only applicable to the live-activity-status-by-user report.

Parameters
userArray
Type: array[string]
Array of user_ids to be added to the report.

Unpause the test for the user IDs provided.

Important Only applicable to the live-activity-status-by-user report.

Parameters
userArray
Type: array[string]
Array of user_ids to be added to the report.

Each of the user IDs provided will navigate to the specified item.

The assessment will be automatically started if the student is still on the intro item.

The item is specified by reference (a string) or number (a 1-indexed number).

Important Only applicable to the live-activity-status-by-user report.

Parameters
userArray
Type: array[userObject]
Array of users to be added to the report.
itemObject
Type: object
object containing either an item_number or item_reference property.
Properties:
item_number
Type: number
item_reference
Type: string

Returns array of user_id strings for the currently selected users.

Important Only applicable to the live-activity-status-by-user report.

Returns: array[string]

Retrieves a specific portion of raw score data that is available to the report, based on a given set of user and tag filters.

This method retrieves the data asynchronously, and returns a promise that resolves with the data.

Important Only applicable to the item-scores-by-tag-by-user report.

Parameters
params
Type: object

A collection of required and optional parameters for selecting and filtering the data to be retrieved.

Properties:
column_tag_types
Type: array[TagsV2|TagSearchByType]

The hierarchy of column tags within which to limit the retrieved data.

There are a number of distinct ways in which to use this parameter:

  • Pass [] to retrieve the overall total scores across all content in the report.
  • Pass an array containing a single TagSearchByType object to retrieve a breakdown of scores for all tag names within that tag type.
  • Pass an array containing one or more TagV2 objects and where the final element is a TagSearchByType object to retrieve a score breakdown for all tag names located at that tag path.
  • Pass an array containing TagV2 objects to retrieve the overall score for all content at that specific tag path (this is a more specific variant of the format above. Use the format above to retrieve scores for all nodes within a tag type, or this format to retrieve just one specific node).
row_tag_types
Type: array[TagsV2|TagSearchByType]

(Optional) The hierarchy of row tags within which to limit the retrieved data.

This parameter behaves similarly to the column_tag_types parameter; see above for details of usage.
user_ids
Type: array[string]
The list of user_id entries in the report for which to specifically retrieve data.

Returns the group path currently displayed in the report..

Important Only applicable to the sessions-summary-by-group and activity-summary-by-group report.

Navigates the report to the given group path.

Important Only applicable to the sessions-summary-by-group and activity-summary-by-group report.

Parameters
groupPathObject
an object containing a reportPathArray.
 
var reportObject = reportsApp.getReport("activity-summary-by-group-report");
reportObject.viewGroup({"path": ["Simpson", "Springfield High"]});

Retrieves the raw JSON data for the specified group path and passes it to a callback.

Important Only applicable to the sessions-summary-by-group and activity-summary-by-group report.

Parameters
reportPathObject
Type: reportPathObject
callback
Type: function
function to be called once the data set has been fetched from Learnosity infrastructure.
Properties:
data
Type: object

See dataset JSON structure sample file for more information.

Sets options on the report. Used to modify or update the report's behavior after initialization.

Important Only applicable to the sessions-summary-by-group and activity-summary-by-group report.

Parameters
options
Type: object

Object containing options to configure UI and behaviour. Contains one or more of the below properties.

Properties:
always_show_group_ancestors
Type: boolean
Flag that specifies whether or not to display the ancestor rows for the current group.
columns
Type: array[object]
A definition of the columns that should be shown in the UI.

See column definitions for more information.

user_columns
Type: array[object]
A definition of the user-level columns that should be shown in the UI.

See column definitions for more information.

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

object
an object containing the user information required to add that user to a live progress report.
Properties:
id
Type: string
the user id that should be tracked in this report. This is the same user_id used when initializing the Items API.
name
Type: string
the user name to be displayed in the UI.
hash
Type: string
a sha256 hash of the user_id and consumer secret.
array[String]
An array containing the group hierarchy path for this report. Shown as an array of strings in descending order.
object
an object containing a reportPathArray.
Properties:
path
Type: reportPathArray
object
Properties:
then
Type: function(ItemScoresByTagByUserData)
catch
Type: function()
object
Properties:
item_tags
Type: object
scores
Type: object 
{
  "item_tags": {
    "ch_curriculum_code": {
      "ACMGM000": {
        "sort_key": 0,
        "description": null
      },
      "ACMGM001": {
        "sort_key": 1,
        "description": null
      }
    }
  },
  "scores": [
    {
      "user_id": "user_20180417a_00001",
      "item_tags": [
        {
          "type": "ch_proficiency_strand",
          "name": "Fluency"
        },
        {
          "type": "ch_topic",
          "name": "2. Matrices"
        }
      ],
      "score": 2,
      "max_score_of_attempted": 4,
      "max_score_of_unmarked": 0,
      "max_score": 4,
      "count": 2
    }
  ]
}
object
Properties:
[tag_type]
Type: object
object
Properties:
[tag_name]
object
Properties:
user_id
Type: string
item_tags
Type: array[TagsV2|]
An array of tags describing the path through the hierarchy that this score belongs to. This includes column and row tags. An empty array represents the overall total score for the given user.
score
Type: float
Sum of scores that has been calculated for the given user and combination of item tags.
max_score_of_attempted
Type: float
For all attempted responses by the given user within the given combination of item tags, this is the sum of the highest scores that can be awarded.
max_score_of_unmarked
Type: float
For all unmarked responses by the given user within the given combination of item tags, this is the sum of the highest scores that can be awarded.
max_score
Type: float
Sum of the highest scores that can be awarded for the given user and combination of item tags.
object
Properties:
sort_key
Type: string
description
Type: string