Visualize xAPI Duration Data with VQL

Visualize xAPI Duration Data with VQL

Would you like to know how much time people spend on your eLearning activities? 

With custom xAPI, you can measure how long people spend on specific slides, modules, questions, quizzes, and courses.

This data can help you identify patterns in user behavior and improve the overall user experience.

So, it’s one thing to collect this data, but it’s another to visualize and act on it.

That’s why, in this tutorial, I’ll show you how to create data visualizations that display the average duration for different activities. This will give you the duration information you need at a glance.

We’ll create the visualizations using Veracity LRS and  Veracity Query Language (VQL).

If you don’t already know how to collect duration information with xAPI, then you should complete the first three tutorials in the Full Guide to xAPI and Storyline, as well as the Measure Duration with xAPI tutorial.

Once you know how to collect duration information, let’s dive in and look at how to visualize it!

What is VQL?

Veracity Query Language, or VQL, is a language developed by Veracity Learning. You can use the language to quickly query and display whatever xAPI data you’d like.

There are many impressive features under-the-hood. For example, VQL opts to use MongoDB, JavaScript, or ElasticSearch (sometimes all in the same query) depending on which language it can use to get the data most quickly.

So, if you’d like to learn VQL to take full advantage of the language, then you should dive into the VQL documentation. If you’re not interested in that, then no worries. I will give you some easy-to-use code that you can copy and paste later in this tutorial.

Get your xAPI Data into Veracity LRS

To take full advantage of VQL and create our visualizations, we need to get our xAPI data into Veracity Learning LRS.

If you do not already have a Veracity Learning LRS account, then you should create one now.

After that, there are a few ways to get your xAPI data into your LRS:

  • Download a .csv from your other LRS provider, then import it into Veracity LRS
  • Set up statement forwarding from your existing LRS provider to Veracity LRS
  • Send the data directly to Veracity LRS from the activity provider 

Once you have xAPI data in your LRS, then you’re ready to create an average duration visualization.

Important Note: Make sure that your xAPI data includes duration information in the “result.duration” property. If your xAPI data does not include this, then look at the tutorials linked in the introduction.

Create a Dashboard

If you do not already have a custom analytics dashboard for your Veracity LRS, then you will want to create one.

First, sign in to Veracity and select the LRS that holds your xAPI data.

Next, select "Analytics" from the toolbar on the left.

Select analytics from the left toolbar

After that, select "Custom Dashboards," then select "New Dashboard."

Select Custom Dashboards then New Dashboard from left toolbar

Now you can select "Edit Dashboard."

Select edit dashboard button

If you'd like, rename the dashboard by selecting the "Set Title" button.

Set Title for the custom dashboard

I suggest creating a dashboard for each “group” of data that you’d like to visualize. For example, if you want to visualize the average durations for every quiz in a course, then you would create a dashboard for the overall course.  

Think of the dashboard as a single-page "folder" for the individual visualizations.

Create the Duration Visualization

Once you’ve created the dashboard, it’s time to create the average duration visualization.

If you have not already selected the “Edit Dashboard” button, then select it now.

Select edit dashboard button

Next, select the “Add Widget” button.

You’ll see a popup with two options. Choose “Advanced Graph Query.”

Select Advanced Graph Query

Now you should delete all of the default code that appears, copy the VQL code below, and paste it into the VQL text box.

{% c-block language="js" %}
{
    filter: {
        "object.definition.type": "http://adlnet.gov/expapi/activities/assessment"
    },
    title: "Enter Your Title Here",
    process:
    [
        {
            $frequentValues: {
                path: "object.id",
                metrics: {
                    duration: {
                        $avg: "meta.duration"
                    }
                },
                sort: {
                    duration: "desc"
                }
            }
        },
        {
            $addFields: {
                durationInSeconds: {
                    $divide:["$duration", 1000]
                }
            }
        },
        {
            $toCanonicalDisplay: {}
        },
        {
            $barChart: {
                categoryPath: "canonical.display",
                valuePath: "durationInSeconds"
            }
        }
    ]
}
{% c-block-end %}

Paste the code into the VQL text box on the left side of the screen

To make sure that this code works with your project, there are a few things that you will need to change.

First, look at the “filter” section of the code (starting on line 2). This filter will “filter” your dataset to only the statements that match the given criteria. 

In the code example above, I filtered the statements to only those where object.definition.type is equal to "http://adlnet.gov/expapi/activities/assessment".

You can change the filter based on the duration data you’d like to see. Use dot notation and the exact value in your xAPI statements to filter them appropriately.

If you’d like to include every statement in the LRS, then delete everything on line 3 of the code that I provided.

Next, change “Enter Your Title Here” to whatever you’d like to title the chart, in quotes. This is on line 5 of the code.

Finally, notice on line 10 of the code that path is set to “object.id”. This shows the average duration for each unique object. If you’d like to show the average duration by user, then you can change “object.id” to something like “actor.name” (although this may vary depending on how your data is structured). 

If you’ve modified the code successfully, then you will see a bar graph with the top ten average durations, in seconds. Press OK to close the query editor window.

Average duration by quiz data visualization

The bars will not appear in descending order (since the chart puts them in alphabetical order after identifying the top ten average durations), but this is getting fixed in an upcoming Veracity LRS update.

If you’d like to learn more about amCharts, the visualization library used by VQL, then you can do so with the amCharts documentation.

Conclusion

And there we have it! You can use the duration data visualizations to identify where users are getting held up in your eLearning experiences, and then you can use that data to make informed improvements to the experiences.

This VQL example is just the tip of the iceberg of what’s possible, and VQL is one of the strongest xAPI query languages available.

If you have questions about xAPI, data visualization, or VQL, then you should join my eLearning Slack community and ask away!

Featured Tutorials

View all tutorials