The guide Managing Measures explains how to use the Measure Editor to create and manage measures. This guide gives more detail on the various settings available when creating measures in simple configuration. See Measure Advanced Configuration for advanced configuration.
Default measures
The measure editor includes all of the default measures. These can be copied and edited to create new measures that follow a similar pattern. The table below lists the default measures and explains their function.
|
Measure |
Details |
|
Interaction Count |
Counts the number of xAPI statements that have an object.id property. Since all statements have an object.id, this equates to counting all statements. |
|
Activity Count |
Counts the number of unique values of object.id in the batch of statements. This is the number of unique activities represented in the statements. |
|
Completion Count |
Counts the number of xAPI statements that have a result.completion property set and with a value of true. |
|
Average Score |
Calculates the mean average of scaled score values. This measure can be easily copied and modified to look at raw score instead. |
|
Total Time |
Adds up the total of all result.duration values. |
Creating and editing measures
See Managing Measures for how to open start creating or editing a measure.
Hint: Often the easiest way to create a new measure is to copy an existing measure.
Simple configuration for measures is extremely powerful and allows you to create a huge variety of measures. The available fields are explained below.
Name and display name
The Name field controls the name of the measure as it appears in the measure editor and the report builder, whereas the Display Name is the name of the measure as it appears in reports. This enables you to use very specific technical measure names such as “Module 7 Scaled Score Average (passes only)” to distinguish between your measures when creating reports, and still display a simple display name such as “Score” in reports.
Measure Category
You can group measures together in categories to make it easier to find them in the report builder. Measure Categories are displayed as bold headings in the Select a Measure drop down.
See Managing Measures for how to create categories which you can select when creating and editing measures.
Filters
The Filters section enables you to enter any number of statement property based filters. You can filter by any statement property and even use the Exclude checkbox to filter statements that do not contain the value entered. For very complex filters or date based filters, you can use the Advanced tab. See Measure editor advanced configuration below.
Value
The Value dropdown offers either a Statement Property or Time Period value. Statement Property values are most common, and you can use Time Period values, for example, to display the first or last time an event occurred.
For Statement Property values, the value used can be any xAPI statement property. Use the Data / Debug page to inspect statements to see the properties you can used. The value box will autofill suggested values. In addition to statement properties defined in xAPI, you can also use some enhanced properties added by Watershed for reporting.
result.durationCentiseconds converts the statement’s duration property from an ISO8601 duration string into a number of centiseconds that can be used in calculations.
actor.person.id uses the Watershed id of the person, rather than the xAPI actor identifier. This is useful, for example, if people are identified by multiple different identifiers but you want to count unique people.
Statement property values involving extensions need to have the property wrapped in square brackets. For example, to get the value of a video's start time usecontext.extensions.[http://id.tincanapi.com/extension/starting-point]
Aggregation
The Aggregation dropdown selects the type of aggregation to be applied to the value. The table below outlines a complete list of possible aggregations. The values given in the example column are based on the data set 5, 3, 2, 2, 3.
|
Aggregation |
Explanation |
Example |
|
Count |
The number of items in the filtered data set. |
5 |
|
List |
The same as Count except when used on leaderboards the value can be clicked to reveal a list of all the items. |
5 |
|
Distinct Count |
The number of unique items in the filtered data set. |
3 |
|
Set |
The same as Distinct Count except when used on leaderboards the value can be clicked to reveal a list of all the items. |
3 |
|
First |
The first (earliest) item in the dataset ordered by statement timestamp. |
5 |
|
Last |
The last (most recent) item in the dataset ordered by statement timestamp. |
3 |
|
Minimum |
The smallest value. |
2 |
|
Maximum |
The highest value. |
5 |
|
Average |
The mean average. |
3 |
Please note: The Distinct Count, and Set aggregations show estimated values in order to increase the loading speed at which reports loads. By default measures of below 1000 values will be exactly right, and ones over 1000 will be accurate to within 1%. This default value can be increased using the Advanced Configuration.
Hint: When you don't care what value is returned, consider using "Any" instead of "Last" or "First". This can be set in Measure Advanced Configuration.
Chart Min and Chart Max
Chart Min and Chart Max are used to set the minimum range that the chart will display. This can be useful if, for example, you want a report of scores out of 100 to show the full range of 0 to 100 range than only showing the range containing values.
Hint: Chart Min and Max look like this in Advanced Configuration.
"min": {
"value": "0"
},
"max": {
"value": "1"
}
Benchmark
Sets a benchmark value for the measure. This is displayed on bar, line and spider reports as a line to indicate if the value is above or below benchmark. On scatter charts displaying quadrants, the quadrants will be adjusted to show above and below benchmark. An example of a benchmark configuration that would be added to a measure is as follows:
"benchmark": {
"type": "SIMPLE",
"value": 75
}
Color
The default color to use for the measure in reports. The input box background will preview the color to be used for the measure.
Visibility
Visibility controls who sees the measure in the report builder. This can be ‘Everyone with permission’ or ‘Hidden’.
Please note: If you want to use a measure in a report but don’t want it to appear in the dropdown for anybody, set the visibility to ‘Everyone with permission’ while you create the report and then go back and change it to ‘Hidden’.
View Permission
Search for groups and people to assign view permissions, or search 'All parts of your organization' to make the measure visible to everybody with report builder access. Remove permissions by selecting Revoke measure view permission.
Users with view permissions for a measure are able to see that measure in the report builder when they configure reports and, if they are area admin users, are able to edit and delete that measure in Measure Editor. Global Admins have permissions for all measures regardless of settings.
Even if a user does not have view permissions for a measure, they will still see that measure in reports that have been configured to use it. They just don't see the measure in the measure drop down when adding measures to reports.