Reporting Extension

NOTE: This is only for customers that have opted to license the Rustici Engine Reporting Extension.

Installing

For .NET Engine installations the Reporting Extension is delivered as a zip file that includes a README and a set of .dll files that need to be installed in the bin/ folder alongside Engine's other .dll files.

For Java Engine installations the Reporting Extension is delivered as a zip file that includes a README and a set of .jar files that need to be installed in the WEB-INF/lib directory of the expanded web application, or where the application container can load the classes.

The Reporting Extension relies on the database schema as defined by Engine, so no additional database installation/upgrade steps need to be performed.

Loading

To enable the Reporting Extension, the Plugins configuration value in the RusticiEngineSettings.configRusticiEngineSettings.properties file needs to be added or updated to include Reporting.Default. The value is a comma delimited string accepting a list of plugin names.

The Reporting Extension must be configured at the system level because the code is loaded at startup. Engine will fail to start if either there is an invalid value for the Plugins setting, or if the setting is valid but a plugin that is intended to be loaded is not found. Because plugins rely on core functionality available in Engine, each plugin has a minimum required version of Engine that it needs to function properly. If this minimum version is not detected when the plugin loads, then Engine will not start. You can contact Rustici support to get an Engine upgrade that will work with the given plugin version.

When properly loaded by Engine, the reportingPlugin entry in the /about API resource response will have an installed property with a value of true.

Configuring

The Reporting Extension relies on three configuration values beyond the Plugins value mentioned above. The values for these configuration settings are provided by Rustici during the Reporting Extension kickoff. The three settings are:

  • ReportingServerUrl
  • AdminReportingKey
  • AdminReportingSecret

These settings are configured at the system level and grant specific access to the Reporting Extension's hosted component which is what Engine internally communicates with to provide the reporting functionality. These settings can be set either in the system configuration file or via the API.

In addition to the above settings specific to the Reporting Extension, the xAPI pipes functionality in Engine must be enabled to populate the reporting service backend system with data. To enable xAPI pipes in Engine set the xAPIStatementPipeEnabled configuration setting to true.

If SCORM and/or AICC course data needs to be made available to the reporting service backend system, then the ConvertTinCanFromScormRealtime and potentially ConvertTinCanFromScormHistorical settings should also be given a value of true. This causes SCORM and AICC based courses to capture data into the xAPI LRS within Engine so that the data will be piped to the reporting service backend.

Enabling/Disabling

The reporting functionality must be enabled on a per-tenant basis. Enabling reporting for a particular tenant is what allows data to flow from the Engine instance to the reporting service backend. Disabling the reporting functionality for a given tenant will also disable the flow of the data to the reporting service, but does NOT remove the existing data from the service. Re-enabling reporting will cause the data to be "caught up" from when it was disabled unless a specific date and time are provided.

To check whether reporting is enabled for a tenant, a GET request should be made to the /api/v2/reporting/enabled resource. To enable/disable reporting for a tenant, a PUT request should be made to the /api/v2/reporting/enabled resource.

Predefined Reports

The Reporting Extension has a set of predefined reports that are easily accessible for the most common use cases. Each of these is an embeddable report that has a predefined set of data that keeps the necessary API complexity to a minimum. The response to the API requests mentioned below is a JSON object containing URLs to two variations of the report: the default and a more simplified version. These URLs can be used to provide a link to the report, to populate an iFrame in your own page, or to open the report in a new window, etc.

Score to Duration Scatter Plot

Access this report by making a POST request to the /api/v2/reporting/report/scoreToTime resource. The body of the request should be a JSON object that must include a list of one or more course identifiers. The data can be further restricted based on a list of learner identifiers and/or a set of date filters. When rendered the report will show a scatter plot of the relation between the amount of time spent in a course and the score achieved.

Single Course Gradebook

Access this report by making a POST request to the /api/v2/reporting/report/singleCourseGradebook resource. The body of the request should be a JSON object that must include a course identifier. The data can be further restricted based on a list of learner identifiers and/or a set of date filters. When rendered the report will display a table with each row corresponding to a learner with data recorded for the course and the values for their score, success (pass/fail), completion, and amount of time spent taking the material.

Multiple Course Gradebook

Access this report by making a POST request to the /api/v2/reporting/report/gradebook resource. The body of the request should be a JSON object that must include at least one course identifier and a measure, which is the value captured from the course(s) that you want to display in the report. The data can be further restricted based on a list of learner identifiers and/or a set of date filters. When rendered the report will display a table with each row corresponding to a learner and a column for each course. For each the learner, the value in each course column will be the value of the requested measure.

Custom Reports

Along with the predefined reports, the Reporting Extension exposes an API for generating custom embeddable reports or for general data retrieval for use in another charting or analytics tool. These reports share a common definition to make them easily interchangeable, allowing for easy creation of multiple views of the same or similar data sets.

Definition

The definition of a report determines the types of data points that will be returned and the restricted portion of the overall data to consider. This is achieved by using a set of "measures", grouping data by a set of "organized bys", and restricting the set via various filters.

Measures

Measures are the data points of interest. They consist of a measure such as raw score, completion, duration, success, etc., an aggregation such as min, max, first, last, sum, etc., and a label which determines the name for that data point. Some reports require specific numbers of or minimum numbers of measures to be provided.

Organized Bys

The aggregation of a measure is applied to data that has been grouped together based on the provided "organized by". An "organized by" is a string that indicates the classification of the data to be grouped, such as learner (identifier), course (identifier), a timeframe (day, week, month, year), activity, or activity type.

Filters

Filters apply to the overall data set and limit the scope of the data that will be considered when producing the report defined by the above two items. Filters are optional in custom reports and can be combined. There are four types of filters: learner (identifier), course (identifier), xAPI activity (identifier), and date.

The identifier based filters allow passing one or more identifiers for specific items. The identifiers used match those already recognized within the Engine instance.

Date filters come in two variations. A "TRAILING" (dateType) date filter allows restricting the data to a particular time period starting from "now" stretching back a certain number (trailingAmount) of days, weeks, months, or years (trailingType). A "CUSTOM" (dateType) date filter allows the specification of a specific date range from a starting date/time to an ending date/time.

Embeddable

Embeddable reports are accessed by making a POST request to the /api/v2/reporting/report/embeddable resource. The body of the request should be a JSON object that must include a kind of report and the report definition as described above.

Kinds
  • Bar - a bar chart with the measures represented as bars
  • Scatter - a scatter plot with measures represented on the X- and Y- axes
  • Leaderboard - a table with the organized bys ordered based on a measure
  • Line - a line chart where measure values are connected
  • Pie - a pie chart where measure values are relatively sized slices of the whole
  • Spider - a spider chart where measure values are visually comparable across organized bys
  • Correlation -
  • Heatmap -
  • Range -
  • Metric - a simple display of a single value
  • Events - a simple list of strings based on the data in an xAPI statement

See the API documentation for an exact list of report kinds.

The response for embeddable report requests is a JSON object containing URLs to two variations of the report: the default and a more simplified version. These URLs can be used to provide a link to the report, to populate an iFrame in your own page, or to open the report in a new window, etc.

Data Export (CSV/JSON)

Data can be exported from the reporting service using the same definition as described above in two different formats.

CSV

To retrieve data as CSV, make a POST request to the /api/v2/reporting/report/csv resource with the definition as described above. The data will be returned with a Content-Type of text/csv and the body of the response will be the CSV formatted data. The first row of returned data will correspond to the measure labels. Each subsequent row of data will begin with the organized by sent with the request, followed by the values for the measures.

For example:

Person,SCORERAW (AVERAGE),EVENTS (COUNT),DURATION (LAST) (seconds)
Lucy Braun,,40,13.15
Rowland Connelly,1.0,36,59.12
Axel Bailey,0.93,34,63.3
JSON

To retrieve data as JSON make a POST request to the /api/v2/reporting/report/json resource with the definition as described above and a structure whose value determines the returned structure. There are two variations of returned structure to handle multiple use cases, an array of objects (ARRAYOFOBJECTS) or an array of arrays (ARRAYOFARRAYS).

For an array of objects, an array will be returned where each element corresponds to the value of the organized by which is included in the object as a property along with a propery for each measure.

For example:

[
    {
       "Person": "Lucy Braun",
       "SCORERAW(AVERAGE)": "",
       "DURATION(LAST)(seconds)": "13.15",
       "EVENTS(COUNT)": "40"
   },
   {
       "Person": "Rowland Connelly",
       "SCORERAW(AVERAGE)": "1.0",
       "DURATION(LAST)(seconds)": "59.12",
       "EVENTS(COUNT)": "36"
   },
   {
       "Person": "Axel Bailey",
       "SCORERAW(AVERAGE)": "0.93",
       "DURATION(LAST)(seconds)": "63.3",
       "EVENTS(COUNT)": "34"
   }
]

For an array of arrays, an array will be returned where each element is an array. The first array will contain metadata for the returned data where its elements are first the organized by label, followed by the labels for each of the measures. The rest of the arrays correspond to the value of the organized by which is the first element of the nested array and the subsequent elements correspond to the measure values.

For example:

[
    [
        "Person",
        "SCORERAW (AVERAGE)",
        "EVENTS (COUNT)",
        "DURATION (LAST) (seconds)"
    ],
    [
        "Lucy Braun",
        "",
        "40",
        "13.15"
    ],
    [
        "Rowland Connelly",
        "1.0",
        "36",
        "59.12"
    ],
    [
        "Axel Bailey",
        "0.93",
        "34",
        "63.3"
    ]
]

Expert APIs

There are additional /advanced resources available via the API documentation, but their usage is beyond the scope of this document. If there is a use-case not covered via the predefined or custom report resources listed above please contact Rustici support for additional assistance.

results matching ""

    No results matching ""