What is Advanced Configuration?
Advanced Configuration enables precise control over creating and editing reports by providing access to options otherwise unavailable in Watershed's report builder. Using JSON, choose what data should be included in reports and configure how that data is displayed.
This guide introduces you to Advanced Configuration and explains how to access and use these advanced report settings. See the related guides listed below for details of specific Advanced Configuration settings.
- User Types
- Any user with access to the report builder (Global Admins, Area Admins, and some Users).
- Available on paid plans (Analyst, CLO, and Enterprise).
- 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 the report builder:
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:
The first section of every report's Advanced Configuration controls 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:
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.
There's lots of useful resources about JSON online. We recommend Introduction to JSON on restfulapi.net as a good place to start, and JSONedit as a nice little tool to play around with to edit JSON as you learn. You can also use JSONLint to check JSON code for errors.
If you make a mistake with the JSON code, Watershed will highlight the error with a red cross next to the line number. In the example below, line 10 shows a red cross because line 9 ends with a comma that should not be there.
The most common JSON errors are missing or extra code characters such as
Advanced Configuration Tips and Tricks
You don't have to write the JSON code yourself and most Advanced Configuration work involves copy-pasting JSON from a help guide or another report, or editing existing properties. The following tips and tricks help make Advanced Configuration a little simpler:
- Make use of Simple Configuration and Measure Editor to take the report as far as you can before switching to Advanced Configuration to make changes.
- You can also jump back into Simple Configuration at any time to make additional changes, even after you have edited the Advanced Configuration.
- Make use of the help guides listed below to copy Advanced Configuration code snippets from the examples, or copy Advanced Configuration from another report.
- After selecting the report type, but before editing the Advanced Configuration, save the report to add additional properties specific to that report type to the configuration. This means you can edit those properties without having to look up or remember what they are to add them.
- If your Advanced Configuration gets messy, you can save the report and re-open it to format the JSON nicely.
- Don't save the report or switch to simple configuration while you have a JSON error as indicated by the little red cross or you could lose your changes. Fix the error first.
- For complex reports, it can be useful to edit the JSON in a text editor and perhaps even save a copy of the configuration to your computer. Sublime Text is one text editor that we use.
- Make comments in your Advanced Configuration using
//to help yourself and others understand why you're using certain filters/settings.
Advanced Data Filters: