Using the Measure Editor (How do I create custom measures?)

Explore comes pre-bundled with a collection of default measures: Activity Count, Interaction Count, Average Score, and Completion Count. These measures can be useful at giving you a high level view of your data, but we recommend that you create measures unique to your data that allows you to go deeper.

The measure editor enables you to create and manage these additional measures for yourself in an easy to use interface. This guide explains how in 7 sections:

The Measure Editor was discussed as part of our Product Walkthrough webinar series. Watch a recording of the webinar for a comprehensive look at application and setup of the feature.

Accessing the measure editor

The measure editor is accessed by selecting Measures on the Settings menu.

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

Often the easiest way to create a new measure is to copy an existing measure by clicking Copy next to the measure you want to copy. You can also create a new measure by clicking Add measure or edit an existing measure by clicking Edit next to the measure you want to edit. All of these approaches open a similar add or edit measure page.

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 explore, 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 cards, and still display a simple display name such as “Score” in reports.

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 use context.extensions.[http://id.tincanapi.com/extension/ending-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 item in the dataset. This is ordered by statement timestamp.

5

Last

The first item in the dataset. This is ordered by statement timestamp.

3

Minimum

The smallest value.

2

Maximum

The highest value.

5

Average

The mean average.

3

You can enter a number representing a benchmark for the measure in the Benchmark field. This is represented visually in different ways on different cards and shows a level that the value is expected to exceed (or stay below depending on the measure).

Visibility

Visibility controls who sees the measure in Explore. This can be ‘Everyone’, ‘Admins only’ or ‘None’.

Please note: if you want to use a measure in a card but don’t want it to appear in the dropdown even for admins, set the visibility to ‘Admins only’ while you create the card and then go back and change it to ‘None’.

Using measures in cards

Once you’ve created a measure that is visible to you, you can select that measure from the Measures dropdown of cards that use measures. The measure remains linked to its definition within the Measure editor, so if you make changes to the measure in the editor, those changes will be reflected in all cards that use that measure.

Please note: updating a measure in the editor may not always cause cards using that measure to re-cache. You may need to wait before seeing the changes reflected in cards.

Deleting measures

Measures can be deleted by clicking the Delete option next to the measure you want to delete in the Measure editor, and selecting Yes to the warning alert. Deleting a measure does not affect cards where the measure is used because a copy of that measure is saved with the card configuration. These copies can only be edited using advanced configuration when editing the card.

Please note: once you delete a measure, there is no way to update all copies of that measure in one place. You would need to re-create the measure and then remove and re-add the measure to all cards on which it is used. Delete carefully!

Measure editor advanced configuration

The measure editor simple configuration is extremely flexible and enables you to create most of the measures you’ll need. There are a few cases where Watershed admins will want to create especially complex measures. For those situations there’s an Advanced tab available when creating or editing a measure. You’ll need to use advanced configuration when:

  • Specifying that the data type of an extension is a duration.
  • Using 'group count' or 'group percent' aggregations.
  • Using a ‘time between’ value producer.
  • Building especially complex measure filters.

These scenarios are explained below.

Value types

The valueType property is used to tell Watershed what data value the value of an extension has. This is especially important for durations. For example:

{ 
  "name": "Start", 
  "aggregation": { 
    "type": "LAST" 
  }, 
  "valueProducer": { 
    "type": "STATEMENT_PROPERTY", 
    "statementProperty": "context.extensions.[http://id.tincanapi.com/extension/starting-point]", 
    "valueType": "duration" 
  }
}

Other Aggregations

Some aggregations are not yet supported by the Measure Editor. 

Group Count

The Group Count aggregation counts the number of people in a group, ignoring any filters. This aggregation only make sense for cards organized by group and uses a statement property value producer of actor.person.id. 

{ 
  "name": "Group Population", 
  "aggregation": { 
    "type": "GROUP_COUNT" 
  }, 
  "valueProducer": { 
    "type": "STATEMENT_PROPERTY", 
    "statementProperty": "actor.person.id"
  }
}

Group Percent

The Group Percent aggregation gives the total number of people matching a filter divided by the number of people in the group, displayed as a percentage. This aggregation only make sense for cards organized by group and uses a statement property value producer of actor.person.id or context.instructor.person.id. 

{ 
  "name": "Percent of People", 
  "aggregation": { 
    "type": "GROUP_PERCENT" 
  }, 
  "valueProducer": { 
    "type": "STATEMENT_PROPERTY", 
    "statementProperty": "actor.person.id"
  }
}

Constant Percent

The Constant Percent aggregation works in a similar way to the Group Percent aggregation except that it shows the distinct count value as a percentage of a fixed constant, rather than by the number of people in a group. The constant is configured using an additional property within the aggregation object. 

{ 
  "name": "Percent of People", 
  "aggregation": { 
    "type": "CONSTANT_PERCENT",
"constant": 45 }, "valueProducer": { "type": "STATEMENT_PROPERTY", "statementProperty": "object.id" } }

Last Between

The Last Between aggregation works in exactly the same way as the Last aggregation except that it only returns a value if the last value is with a particular date range. This is useful for identifying events that have happened most recently within a date range and not more recently, for example people who have completed a particular compliance course in the last year, but have not retaken it in the last 11 months. 

{
  "name": "Upcoming Expiration",
  "aggregation": {
    "type": "LAST_BETWEEN",
    "from": "P365D",
    "to": "P334D"
  },
  "valueProducer": {
    "type": "STATEMENT_PROPERTY",
    "statementProperty": "timestamp"
  },
  "filter": {
    "equals": [
      {
        "fieldName": "result.completion",
        "values": {
          "ids": [
            "true"
          ]
        }
      }
    ]
  }
}

Please note: you can use the LAST aggregation with a trailing date filter to get people who have taken the course in the last 11 months.

Expired

The Expired aggregation is used to identify people who have never completed something, or have completed it prior to a certain date. Again, this aggregation is useful for tracking compliance. The aggregation will return "never" if people have no statements matching the measure's filter. It will return the value of the most recent statement prior to the configured date if they do have matching statements only prior to that date. It will return nothing if they have matching statements after the configured date. 

Putting this into the context of compliance, this measure would return nothing for people who are compliant, the date when they last became compliant if they were compliant but aren't any longer, or 'never' if they have never been compliant. 

{
  "name": "Not Completed",
  "aggregation": {
    "type": "EXPIRED",
    "date": "P1Y"
  },
  "valueProducer": {
    "type": "STATEMENT_PROPERTY",
    "statementProperty": "timestamp"
  },
  "filter": {
    "equals": [
      {
        "fieldName": "result.completion",
        "values": {
          "ids": [
            "true"
          ]
        }
      }
    ]
  }
}

Other Types of Value Producer

Simple configuration supports the Statement property and Time period. Other types of value producer and their functionality are outlined below.

Time Between

The time between value producer looks at the time between two events, for example the time between starting one task and getting to another one. It uses a start filter and an end filter to find pairs of statements, then calculates the time difference between the two. Depending on the aggregation it'll then either sum, average or take one of those durations to present. For example:

{
  "name": "Most Recent Time Between Activity 1 and Activity 2",
  "aggregation": {
    "type": "TIME_BETWEEN"
  },
  "valueProducer": {
    "type": "TIME_BETWEEN",
    "startFilter": {
      "activityIds": {
        "ids": [
          "http://example.com/expapi/activities/example-1"
        ]
      }
    },
    "endFilter": {
      "activityIds": {
        "ids": [
          "http:/example.com/expapi/activities/example-2"
        ]
      }
    }
  }
}

Measure Filters

You can configure simple measure filters in simple measure configuration. See the filters section of the advanced configuration help guide for details of how to customize these simple filters for more complex requirements.

Video Walkthrough

As part of our Product Walkthrough webinar series, Andrew Downes gave us a a comprehensive look at the Measure Editor. Check it out below:

 
Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

If you can't find what you need or you want to ask a real person a question, please contact customer support.