Advanced Configuration

What is Advanced Configuration?

Advanced Configuration in Explore enables precise control over creating and editing reports by providing options unavailable in Simple Configuration. Using JSON, choose what data should be included in reports and configure how that data is displayed.

Who can use this feature?
 User Types
Any user with access to Explore (Global Admins, Area Admins, and some Users).
 Pricing 
Available on paid plans (AnalystCLO, and Enterprise).
 Expertise
Advanced Configuration is designed to be used by expert users who understand JSON and the properties of xAPI statements.

Accessing Advanced Configuration

To open Advanced Configuration, click Advanced Configuration in Explore: Advanced Configuration

The Advanced Configuration panel will open. It enables you to edit the report's configuration JSON object which defines the filters and settings of reports:Advanced Configuration P
  anel

The first section of every report's Advanced Configuration control the report's Advanced Data Filters. These filters determine the set of xAPI statements that make up the data analyzed in the report. The remaining sections of the Advanced Configuration control how that report's data is displayed.

Switch back to Simple Configuration by clicking Simple Configuration:Simple Configuration

When creating reports, you can switch between Simple Configuration and Advanced Configuration.

 Heads up: A couple of notes about switching between Advanced Configuration and Simple Configuration:

  • We recommend creating as much of the report as possible using Simple Configuration first then switching to Advanced Configuration rather than writing the Advanced Configuration from scratch.
  • Any edits made in Advanced Configuration could be undone by making edits in Simple Configuration.

Advanced Data Filters

The first section of every report's Advanced Configuration control the report's Advanced Data Filters. These filters control the data that makes up your report. Learn how to set up Advanced Data filters.

TimeZone

The timeZone property sets the timezone used by the report. It can also be configured within the date section of Simple Configuration.

Custom dimensions

Several reports (such as Leaderboard and Correlation) aggregate data using dimensions and measures. In Simple Configuration, dimensions are represented by the Organized field. Data can be organized by person, group, day, week, month, year, activity or activity type. If the dimension you need is not on that list, you can use advanced configuration to create a custom dimension. For example perhaps you want to organize data by a context property such as a context activity or instructor.

Constant Dimension

The CONSTANT dimension does not split the data at all and shows measure values for one item representing all the data

Property

Explanation

Example

type

The type of dimension

CONSTANT

For example:

"dimensions": [{
  "type": "CONSTANT"
}]

Statement Property Dimensions

Statement property dimensions break data into items based on the value of a specified statement property.

Property

Explanation

Example

type

The type of dimension

STATEMENT_PROPERTY

statementProperty

The property of the xAPI statement to organize data by.

actor.person.id

caseSensitive

Defaults to true. If false, items that are the same in all but case will be grouped together. This is especially useful when organizing by the result.response statement property.

false

Here’s a complete example that organizes by parent context activity:

"dimensions": [
  {
    "type": "STATEMENT_PROPERTY",
    "statementProperty": "context.contextActivities.parent.id"
  }
]

Here’s another example that organizes by a context extension:

"dimensions": [
  {
    "type": "STATEMENT_PROPERTY",
    "statementProperty": "context.extensions.[http://example.com/xapi/extensions/context/example]"
  }
]

Here’s an example that organizes by response case insensitively:

"dimensions": [
  {
    "type": "STATEMENT_PROPERTY",
    "statementProperty": "result.response",
    "caseSensitive": false
  }
]

Where you need to organize by the value of an extension held in an array, you need to use the __arr__ syntax. For example, the following will organize by values of the 'label' property of objects held in an array within the 'value' property of an extension.

{
  "type": "STATEMENT_PROPERTY",
  "statementProperty": "object.definition.extensions.[http://example.com/extension/example].value.__arr__.label"
}

Histogram Dimensions

When working with numerical values, it can often be useful to group those values into buckets. For example, perhaps you want to report on how many times people pause a video at different points in the video. It would be unhelpful to compare every possible video duration value down to the millisecond, but by grouping duration values into buckets of 1, 5 or 10 seconds, you can get a much clearer picture. The Histogram Dimension enables you to do exactly that.

Property

Explanation

Example

type

The type of dimension.

HISTOGRAM

statementProperty

The property of the xAPI statement to organize data by. 

context.extensions.[http://id.tincanapi.com/extension/ending-point]

valueType

The data type of the statement property. Use this when the statement property is an extension

duration

interval The size of each bucket in whatever units the statement property is measured in. For example, durations are measured in centiseconds (100ths of a second). 1000
minCount The minimum number of statements required for a bucket to appear on the report. This defaults to 1 and cannot be 0 (or negative). Use this if you only want to show buckets that have a minimum amount of data. 1
minValue The starting point for the first item to display. Statements with a statementProperty value lower than this minimum will be ignored. null
maxValue The top value for the last item to display. Statements with a statementProperty value higher than this maximum will be ignored. null

The example below shows how to use a histogram dimension to look at a video in 10 second intervals between 30 and 60 seconds.

"dimensions": [{
  "type": "HISTOGRAM",
  "statementProperty": "result.durationCentiseconds",
  "interval": 1000,
  "minCount": 1,
  "minValue": 3000,
  "maxValue": 6000
}]

Time Period Dimensions

Time period dimensions group statements together by time period. 

Property

Explanation

Example

type

The type of dimension.

TIME

timePeroid

Used with the TIME type to specify the time period.

YEAR

format

Used with the CUSTOM timePeriod format to specify a custom time period. Here's a list of allowed format values

ha 'on' E

Here’s an example that organizes by hour of the day. Labels display values like "1PM":

"dimensions": [
  {
    "type": "TIME",
    "timePeriod": "CUSTOM",
    "format": "ha"
  }
]

Here’s an example that organizes by day of the week. Labels display values like "Tuesday":

"dimensions": [
  {
    "type": "TIME",
    "timePeriod": "CUSTOM",
    "format": "E"
  }
]

Here’s an example that organizes by hour of the day and day of the week combined. Labels display values like "1PM on Monday":

"dimensions": [
  {
    "type": "TIME",
    "timePeriod": "CUSTOM",
    "format": "ha 'on' E"
  }
]
Please note: The dimensions property contains an array of dimension objects. At the time of writing only the line report uses more than one dimension. Additional dimensions after the first will be ignored.

Custom measures

Several reports (such as Leaderboard and Correlation) aggregate data using dimensions and measures. In Simple Configuration, measures are represented by the measures dropdown and list, or simply as two dropdowns in the case of the Correlation report.

The easiest way to create a custom measure is to use the Measure Editor. Details of advanced measure configuration are outlined in the Measure Editor guide.  

Additional Statement Properties

For the most part, Watershed's filters, dimensions and measures use the properties defined as part of xAPI statements. There are some additional properties that Watershed adds to the data for the purposes of reporting. Most of these are added within the statement's actor property and include additional metadata about the person who the statement is about.

Person metadata can be accessed using the actor.person property. actor.person.id matches the Watershed id of the person the statement is about. actor.person.name matches the name of the person the statement is about as defined within Watershed. This can sometimes be different from the value of actor.name, which is the name of the actor as defined in the xAPI statement. actor.person.email matches the email address as defined in Watershed. Unlike actor.mbox, actor.person.email is not prefixed with "mailto:" and therefore looks nicer in reports.

Another peice of metadata that can be accessed is the number of centiseconds represented by the result.duration property. In xAPI result.duration is measured using an ISO 8601 duration string such as 'PT6H34M65.56S'. As this can include hours, minutes, seconds, or even years, months and weeks, it can be difficult to compare duration values in reports. Watershed therefore adds a result.durationCentiseconds property that translates the duration into centiseconds (100th's of a second) to be more easily compared in reports.

Please note: The calculation of result.durationCentiseconds assumes that the duration includes no leap time such as leap years and leap seconds.

Color

The colors used in Watershed reports can be customized at the whole account, measure and report level.

Customization at the report level is done using the colors Advanced Configuration property. This includes a list of valid CSS colors to be used in reports. For example the code below is used to set the chart colors to red, blue and green.

"colors": [
  "red",
  "#00ff00",
  "rgb(0,0,255)"
]

Caching

Report results are cached to improve performance. By default the cache duration is 1 hour, which means that when you view a report, data can be up to an hour old. You can adjust the number of minutes data will be cached for by using the cachingMinutes property. This contains an integer number of minutes Watershed will wait before checking for new data. Decrease this to get more immediate results; increase it to improve the speed and performance of your dashboard.

Custom report text

Watershed’s Simple Configuration enables you to edit the report title, summary and description. Some additional pieces of text on some types of report is editable using Advanced Configuration. Currently, Leaderboard and Accomplishment reports offer editable text.

Leaderboard

The report text property on leaderboards takes this structure:

"reportText": {
  "reportView": {
    "dimension": "{{dimension}}"
  },
  "detailView": {
    "dimension": "{{dimension}}",
    "sentence": "{{activityCount}} distinct {{activityName}} for {{peopleCount}} distinct {{peopleName}} {{observedVerb}} over {{dimensionCount}} distinct {{dimension}}."
  }
}

The reportView object controls what text is displayed when the leaderboard is viewed as a report on the dashboard. The detailView object controls what text is displayed when the full report detail is viewed. {{placeholders}} are used to fill in variable values.

The table below explains the allowed properties of these objects.

Property

Explanation

dimension

The header of the first column of the leaderboard. By default this is the name of the dimension. Only supports the dimension placeholder.

sentence

The text of the sentence displayed at the top of the leaderboard. This sentence will only appear if the report’s showSentence property is set to true. Supports all Leaderboard placeholders.

The table below explains the allowed placeholders.

Placeholder

Explanation

activityCount

The number of activities in the filtered result set.

peopleCount

The number of people in the filtered result set.

dimensionCount

The number of dimension items in the filtered result set, for example if the report is organized by weeks, this would be the number of weeks.

activityName

Either “activity” if activityCount is 1 or “activities” otherwise.

peopleName

Either “person” if peopleCount is 1 or “people” otherwise.

observedVerb

Either “was observed” if peopleCount is 1 or “were observed” otherwise.

dimension

The name of the dimension.

Accomplishment

The report text property on accomplishment reports takes the following structure:

“reportText”: {
  "peopleLabel": {
      "singular": "person",
      "plural": "people"
  },
  "progressCategories": {
      "notStarted": "Not started",
      "lessThanEqual50": "Less than or equal to halfway complete",
      "greaterThan50": "Greater than halfway complete",
      "complete": "Completed"
  },
  "reportView": {
      "summary": "{{registeredPercent}}% of your {{selected}}people are registered for this accomplishment."
  },
  "progressChart": {
      "title": "Progress of {{selected}}registered people",
      "selected": {
          "somethingSelected": "selected ",
          "nothingSelected": ""
      },
      "toogtip": {
          "label": "<b>{{progressCategory}}:</b> <div>{{progressPercent}}% of registered people</div>"
      },
      "legend": {
          "label": "{{progressPercent}}% - {{progressCategory}}"
      }
  },
  "microView": {
      "sentence": "{{completedPercent}}% of registered people have completed this accomplishment."
  },
  "header": {
      "titleSuffix": " for {{groupName}}",
      "sentence1": "{{registeredCount}} out of {{orgCount}} people are registered for this accomplishment.",
      "sentence2": "{{completedCount}} out of {{registeredCount}} registered people have completed this accomplishment."
  },
  "interactionTimeline": {
      "title": "Interaction Timeline{{titleSuffix}}",
      "weekLabel": {
          "singular": "week",
          "plural": "{{weeks}} weeks"
      },
      "timelineLabel": {
          "interactions": "Last {{weekLabel}} of interactions",
          "noInteractions": "No interactions"
      }
  },
  "groupLeaderboard": {
      "title": "Group Leaderboard{{titleSuffix}}",
      "searchPlaceholder": "Search for group name",
      "toogtip": {
          "label": "{{completedPercent}}% of registered people are<br>{{completedStatus}}"
      },
      "sortLabels": {
          "group": "Group",
          "completed": "Completed",
          "avgScore": "Avg Criteria Score",
          "progress": "Accomplishment Progress"
      }
  },
  "personLeaderboard": {
      "title": "Leaderboard{{titleSuffix}}",
      "searchPlaceholder": "Search for person's name",
      "sortLabels": {
          "people": "People",
          "completion": "Completion Probability",
          "avgScore": "Avg Criteria Score",
          "history": "Interaction History"
      }
  },
  "criteriaList": {
      "title": "{{criteriaName}}",
      "description": "{{criteriaDesc}}",
      "sentence": "{{completedCount}} out of {{registeredCount}} people have completed this criteria ({{completedPercent}}%)"
  },
  "sequenceHeatmap": {
      "title": "Criteria Completion Sequence{{titleSuffix}}",
      "xAxisCategory": "Step {{stepId}}",
      "yAxisCategory": "{{criteriaName}}",
      "toogtip": {
          "label": "{{completedPercent}}% of registered people completed <br><b>{{criteria}}</b> as {{step}}"
      },
      "dataLabels": {
          "label": "{{completedPercent}}%"
      }
  },
  "groupHeatmap": {
      "title": "Group Criteria Completion{{titleSuffix}}",
      "searchPlaceholder": "Search for group name",
      "toogtip": {
          "notComplete": "Criteria has not been completed by anyone in the group.",
          "complete": "{{completedCount}} registered {{peopleLabel}} in <b>{{group}}</b> completed <br><b>{{criteria}}</b>.",
          "avgScore": "<br>Avg Score: {{avgScore}}",
          "avgDuration": "<br>Avg Duration: {{avgDuration}}"
      },
      "dataLabels": {
          "label": "{{completedPercent}}%"
      }
  },
  "personHeatmap": {
      "title": "Criteria Completion{{titleSuffix}}",
      "searchPlaceholder": "Search for person's name",
      "toogtip": {
          "notComplete": "Criteria not completed",
          "complete": "Date completed: {{completedDate}}",
          "avgScore": "<br>Avg Score: {{avgScore}}",
          "avgDuration": "<br>Avg Duration: {{avgDuration}}"
      },
      "dataLabels": {
          "complete": "Completed",
          "notComplete": "Not completed"
      }
  }
}

The table below explains where each of the top level properties appear on the accomplishment report.

Property

Explanation

peopleLabel

Controls the terms used for “person” and “people”. E.g. “learner” and “learners”.

Currently this only affects tooltips in the Group Criteria Completion visualization via the peopleLabel placeholder.  

progressCategories

The labels for different progress categories. These are used for the legend on the pie chart on report view and within the tooltips of the Group Leaderboard visualization. This property does not support any placeholders.

reportView

Text at the bottom of report view. Supports registeredCount and registeredPercent placeholders.

progressChart

The pie chart on report view. Incorporates the legend labels defined in progressCategories using the progressCategory placeholder. Also supports the progressValue placeholder.

microView

The text displayed when the report is viewed as part of a group report preview. Supports completedCount and completedPercent placeholders.

header

The two sentences at the top of the report. Supports registeredCount, orgCount and completedCount placeholders.

Also controls the title suffix that is added to the title of each visualization if the report is filtered for a single group. This supports the groupName placeholder.

interactionTimeline

Controls text on the Interaction Timeline visualization. Supports titleSuffix, weeks and weekLabel placeholders.

groupLeaderboard

Controls text on the Group Leaderboard visualization. Supports titleSuffix, completedCount, completedPercent and completedStatus placeholders.

personLeaderboard

Controls text on the Group Leaderboard visualization. Supports the titleSuffix placeholder.

criteriaList

Controls text for each item of the Criteria List visualization. Supports the criteriaName, criteriaDesc, completedCount, completedPercent and registeredCount placeholders.

It is not possible to edit the title of the Criteria List visualization.

sequenceHeatmap

Controls text on the Criteria Completion Sequence visualization. Supports titleSuffix, stepId, criteriaName, completedPercent, criteria and step placeholders.

groupHeatmap

Controls text on the Group Criteria Completion visualization. Supports titleSuffix, avgDuration, avgScore, criteria, completedCount, completedPercent, group and peopleLabel placeholders.

 

Controls text on the Criteria Completion visualization. Supports titleSuffix, avgDuration, avgScore,and completedDate placeholders.

The table below explains the placeholders.

Placeholder

Explanation

registeredCount

The number of people registered for the accomplishment and included by the report’s people and groups filter.

registeredPercent

The percentage of people registered for the accomplishment from those included by the report’s people and groups filter.

orgCount

The number of people included by the report’s people and groups filter.

completedCount

The number of people who have completed the accomplishment or criteria and included by the report’s people and groups filter.

completedPercent

The percentage of people who have completed the accomplishment or criteria from those included by the report’s people and groups filter.

completedStatus

The text for the appropriate progress category (completed, not started etc.) as defined in the progressCategories property.  

progressCategory

The text for the appropriate progress category (completed, not started etc.) as defined in the progressCategories property.  

progressPercent

The percentage of people that fall within the current progress category.

groupName

The name of the group the report is filtered by. This is only used if the report is filtered by exactly 1 group.

titleSuffix

The text defined in the header.titleSuffix property.

weeks

The number of weeks that the interaction timeline is displaying data for.

weekLabel

The text defined in the interactionTimeline.weekLabel property.

peopleLabel

The relevant word for person or people as defined in the peopleLabel property.

criteriaName

The name of the criteria.

criteria

The name of the criteria.

criteriaDesc

The description of the criteria.

stepId

“Step “ followed by the number representing the order the criteria was completed in. E.g. “Step 1”.

step

“Step “ followed by the number representing the order the criteria was completed in. E.g. “Step 1”.

avgDuration

The average duration relating to completion of the criteria.

avgScore

The average score relating to completion of the criteria.

Report specific Advanced Configuration options

Some report types have additional advanced configuration properties relating to specific settings for that report type. These can all be set in Simple Configuration, so we recommend using Simple Configuration for those properties.

If you are creating reports via API, you do not have the option to use Simple Configuration. This section outlines additional advanced configuration properties that are used with specific reports.

Accomplishment

Property

Explanation

Example value

accomplishmentId

The id of the accomplishment the report is reporting on.

1

Activity

Property

Explanation

Example value

surveyMode

If true, the report assumes that data represents survey data and hides any information relating to scores, success or answering questions correctly/incorrectly. Multiple choice options are displayed as multicolored bar charts instead of the grey normally used for incorrect answers. 

false

Bar

Property

Explanation

Example values

defaultSort

How the data should be sorted by default.

“-dimension[0].label”

“measure[1].value”

vertical

If true, the bar chart will display vertical bars; otherwise the bars will be horizontal.

true

singleGraph

If true, the data will be displayed as a single graph; otherwise it will display a graph per measure.

false

The value of the default sort property contains four pieces of information:

  1. Whether to sort accessending (default) or descending ("-" prefix).
  2. Whether to sort by a dimension or by a measure.
  3. The index of the dimension or measure to sort by.
  4. Whether to sort by the measure value or by it’s label.

Group

Property

Explanation

Example values

reportGroupId

The id of the report group to display..

345

Heatmap

Property

Explanation

Example values

showValues

Whether or not to show values on heatmap grid squares.

null

If show values is null, the report viewer will be able to select whether or not to show values in the UI, without having to use Explore.

Line

Property

Explanation

Example values

line

If true, the graph will display as a line. If false, it will display a line with the area under the line filled in.

false

allowGaps

If true, where there is no data for a particular point along the y axis, Watershed will leave a gap to indicate this.  

If false, Watershed will join all the dots with a line across the gap.

true

fillGapsWithZeroes

If true, Watershed will assume points with no data are 0. The value of allowGaps will be ignored.

This is the most appropriate option for count based measures.

false

singleGraph

If true, the data will be displayed as a single graph; otherwise it will display a graph per measure.

false

defaultSecondDimensions

When a second dimension is used, this property defines a list of items that are selected by default and shown on the graph. 

["apple", "orange"]

Leaderboard 

Property

Explanation

Example value

showSentence

If it's included with a value of true, the leaderboard will include a summary sentence at the top.

false

hideDimension

If it's included with a value of true, the leaderboard will hide the dimension column and only display measure values.

true

Pie

Property

Explanation

Example value

includePeopleWithoutStatements

If true, the pie chart will include all people who match the report filter, regardless of whether they have any statement data. This is useful when you want to see which or how many people in a group have not done something. 

false

colors

A list of colors to be used for slices of the pie. 

[
"#80C663",
"#F1FC74",
"#D85353"
]

Scatter

Property

Explanation

Example value

showQuadrants

If true, will show a quadrants background image. The bottom boundaries of the A quadrant are the benchmarks defined for each measure, or the average value for measures with no benchmarks defined. The A+ quadrant within the A quadrant is always half way between the bottom boundary of the A quadrant and the chart maximum. 

false

Program

Program advanced configuration is covered in a separate article.

Was this article helpful?
0 out of 0 found this helpful

Comments

0 comments

Please sign in to leave a comment.

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