For on-premises enterprise customers, you can customize your server with additional widgets through an easy-to-use API.

Custom Dashboards

How to Create a Custom Dashboard

When you select a widget, one will be added to the dashboard. The layout engine will choose a location and size for the widget, which you can edit later. If the widget expects configuration, its configuration dialog will appear.

Every widget exposes a set of parameters that modify how the widget works. Generally, widgets expose properties to help scope their chart to a particular actor, object, or verb. Many also let you override the global time range. You must click the Ok button to save the parameters. Click the Cancel button to discard the changes.

You can remove, move, and size, and configure widgets with the menu on the top right. These options are only visible when the dashboard is in "Edit mode". Click the Edit Widget icon to launch each widget's configuration dialog. You can move the widget by clicking the top center movement icon, and you can resize it by clicking and dragging the corners. The layout engine will move other widgets around as necessary.

You might find that your parameters result in an empty chart. This simply means that there is not enough data to display a chart.

When you exit Edit mode, if a widget doesn't have enough data to display, then it will be hidden completely.

The Chart Builder

The Chart Builder widget presents a flexible and user-friendly form for building bar, pie, and timeseries charts, including split or multiple series.

The Chart Builder is divided into four major sections. On the left is the series editor form where you'll make all your configuration changes. Top right is the render preview. Bottom right, you'll find both the full data returned by the analysis, and the computed query Veracity Query Language (VQL). You can use the VQL in a variety of places to reproduce this chart.

Series Editor Form

Render Preview Returned Data (left), Computed VQL Query (right)

The render preview will update automatically as you make changes to the chart.

Series Options When Chart Type Is Bar or Pie

1. Series Title — This is a title for each series. In a multi series chart, the legend will use this title to label the columns or slices.
   
2. Make a column for each unique value of — This allows you to specify a path into an xAPI statement. The chart builder will generate one column or slice for each unique value found on this path.
   
3. Set the height (or width) of the (column or slice) to — This selects a metric setting the value of the column or slice. By default, the value is the Total Count of the statements that have the given unique value (see above). You can change this to a metric aggregation such as the Average, Sum, Standard Deviation, Minimum, Maximum, or Unique Count across some field.
   
4. Of the values at — When the value of the bar or slice is not the count, you can tell the system what values to include when taking the average, sum, etc. Supply a path into an xAPI statement that selects a number (See note below*).
   
5. Sort By — By default, you'll get the top ten columns or slices by the count of statements that have the unique value on the supplied path. Even if the value of the bars is some metric, you'll still sort by the count by default. If the sort is not set or is Count descending (or Count ascending), then you're showing something like "scores of the most (or least) common students." Set the sort order to Metric descending (or Metric ascending) to show "highest (or lowest) scoring students", which may not include the most frequently seen actors.
   
6. How many columns to show — The number of columns or slices to compute.
   
7. Matching statements where — This lets you filter the dataset based on any path and value.

*If you want to choose an xAPI statement duration property as a value path, then don’t use result.duration. It returns a string value: e.g., PT36.69S. Use meta.duration instead. It returns an integer value, in milliseconds: e.g., 36690.

The below image shows the configuration to find the top ten most frequently seen actors across all data (within the globally selected time range).

This image shows the same actors but makes the value of the bar the average of each actor's scaled score.

Now, we change the sort order to Metric Descending to select the ten actors with the highest average score.

This version adds a filter, so we're seeing the top scoring actors in only the "Data Science" course.

Splitting and Adding Series

Split Series

You can subdivide each bar based on the uniqueness of some other field. Click + Split Series at the bottom to do so. When you add a series split, you'll see these values in the Series Split portion of the form.

This chart shows a bar chart of the most frequent actors, split by the object.

Split series charts ignore the metric of the original series. Instead, the value of the bar is the sum of all its split sections. You can configure the metric for the series split just like the original series.

Multi Series

You can plot two different series side-by-side along the X-axis. The rendering engine will attempt to group the bars by common values on the X-axis. If you don't select a query that generates the same X-axis values for both series, each entire chart will appear in order on the X-axis.

Here's a chart showing students' average scores versus their standard deviation.

This chart plots students in one series and courses in the second. We end up with two different charts side-by-side on the X-axis.

To add a series, click + Add Series at the bottom of the Series Editor form, which adds a blank series that you must fill-in.

Another easier way to add a series is to build the first series, and then click + Duplicate Series inside the form and change the duplicate only as much as needed.

Series Options When Chart Type Is Timeseries

1. Series Title — This is a title for each series. In a multi series chart, the legend will use this title to label the lines.
   
2. The field representing the time value is — Choose a path to a time value in the xAPI statements. This is usually either timestamp or stored but could be some extension value. 
   
3. Set the value of the line at each time to — This selects a metric setting the value of the series. By default, the value is the Total Count of the statements that fall on the given day. You can change this to a metric aggregation such as the Average, Sum, Standard Deviation, Minimum, Maximum, or Unique Count across some field.
   
4. Of the values at — When the value of the series is not the Total Count, you can tell the system what values to include when taking the average, sum, etc. Supply a path into the xAPI statement that selects a number.
   
5. Matching statements where — This allows you to filter the dataset based on any path and value.

This image shows the total count of statements over time.

This image shows the average score for one course over time.

Split Timeseries

Some series may not extend to the bounds of the chart, and some series may not have data at every time interval.

Multi Timeseries

The List Builder

1. ${value._id} — This is the value of the field selected in the "Make an entry for each unique value of" part of the configuration.
   
2. ${value.canonical.display} — If the value at the _id is the URI of an actor, activity, or verb, then value.canonical will automatically be populated with the canonical representation of the object. value.canonical.display always returns the best available display name for the object. In general, it's best to make lists over the IDs of things and use the canonical value for display. This prevents a change in a course title or actor name from being counted as a new course or actor. The chart renderer does this for you automatically, but you'll need to let us know using the JavaScript syntax in the List Builder.
   
3. ${value.count} — The number of statements that matched the unique value of the list entry.
   
4. ${value.metric} — The computed metric value.

Look in the Returned Data window in the lower-right of the List Builder to see all the values available in the selected path.

You can use expression substitution to perform some simple arithmetic in the interpolated string: like ${value.metric * 100}.

The Metric Builder