What are canonical activities?
As xAPI statements flow into the Veracity LRS, it builds a “canon” of names for activities. For example, the LRS can extract the names and hierarchy of courses and their nested lessons and interactions from the IDs, names, descriptions, object types, and extensions of objects and parent and grouping contexts that the LRS finds in xAPI statements.
Ideally, more statements, with more details about activities improves the canon. However, these canonical activities may have names with illegal characters, be too long, or be inconsistent among each other.
For example, suppose a courseware author were too verbose and gave a long title to one of their lessons. To make room for the long label on one axis, the LRS may compress the chart in a widget on the other axis, like this…
But there's good news! The LRS made the labels from text it extracted from xAPI statements and keeps them in a table of canonical activities, which (with permission) you can edit!
How do I edit canonical activities?
1. In the left menu, click Management > All Management Tools. In the Management page, under Data and Analytics, click View Data, to open the View All Data menu.
2. Click View Canonical Activities in the lower-right corner of the menu to open the Canonical Activities table.
A shortcut to get to the Canonical Activities table is, from the <Store> Home page, in the block that lists metrics for the store, click the “Activities” metric label.
You can also click on any object in the Statement Viewer to open that object in the Canonical Activities table.
3. In the input field below the heading of the Display column, enter any of the text of the label.
4. Flip pages and scroll to find the activity you want to change.
5. To the right of the activity row, click the Actions menu button, and select Edit.
6. In the Edit Canonical Activity screen, in the Override Name field, enter a shorter name.
7. At the bottom-right of the screen, click the Edit Activity button.
If the browser window with the chart is still open, click the Widget Actions button in the top-right and select Reload. The widget should re-render the chart better.
The LRS should replace the object ID in widgets with the canonical name. But not all widgets automatically substitute canonical names, and widgets in custom dashboards may need more attention. In Chart Builder widgets, you must make sure Data Settings > Disable Auto Lookup of Agents, Verbs and Activities is off (it’s off by default). In a Custom VQL Query, you must add a $toCanonicalDisplay command.
Why would I edit canonical activities?
Entering a shorter object name to override a long one isn't the only benefit of editing the canonical activities. Here are some others.
As mentioned, some characters in object names don't survive the conversion to xAPI. You can edit the canonical activities to change or remove ruined quotation marks, ampersands, and carriage returns.
Another common reason to re-name objects is to set them in order by adding a prefix number. For example, in a self-efficacy survey, change the canonical names of the buttons to
1 No Idea,
2 Not Sure,
3 Think So, and
4 I Know It. This lets chart widgets in the LRS sort a category axis or legend logically. Imagine how much more legible a chart of responses to a
Likert interaction will be when you change the names of the buttons from
Agree,
Disagree,
Neutral,
Strongly agree, and
Strongly disagree (their default alphabetic order); to
1 Strongly agree,
2 Agree,
3 Neutral,
4 Disagree, and
5 Strongly disagree.
Re-naming pages with a prefix number helps with many queries that use the object ID of the page as a path. For example, if you filter to show only assessments, then having a page number prefix helps you sort them so you can see trends in performance in order, over the course of the training. When re-naming pages, use a logical and ordinal naming convention, such as 1.23 Quiz – Use Cases where 1 is the number of the lesson and 23 is the two-digit number of the page. You may have to include padding zeroes to improve the sort: e.g., 01.01 Intro to Lesson 1.