How to Void an xAPI Statement

30 June 2016 by Ryan Smith

Over the past few weeks, we’ve been looking at the purpose and set-up of the various APIs that make up the Experience API, and most recently, how to query the Statement API.

However, it’s also worth knowing how and why you might want to void a statement – and that, friends, is what we’re going to look at today.

Voiding xAPI Activity Statements

Voiding is fairly straightforward but calls into question the immutability of xAPI data – that data stored there will last forever.

First up, it is important to note that there is no such thing as ‘deleting’ an xAPI statement; they can only be voided. Voiding statements is simply the xAPI way of noting that something was recorded incorrectly.

Why void a statement anyway?

It is rare that you would ever need to void a statement – but there are occasions where you may need to in order to remove a subjective record of activity (such as an incorrect exam mark).  This may occur, for example, if there had been a bug that caused hundreds of object views to be recorded against an actor who hadn’t in fact viewed those objects; or if a learner thought they were logged in to their own training profile but actually were still logged in as someone else and their activity needed to be transferred to their own learning record.

If you void a statement by accident, you cannot undo the void; instead you would need to repost the statement using the correct details. This creates a new statement with a new Statement ID, and a new time posted timestamp, but all other details remain the same.

What happens to a voided statement?

‘Voided’ is the only protected verb in the xAPI dictionary, and it has a special meaning in that it forces the LRS to take an action – to void another statement. So for example, if you had 1000 statements that you wanted to void, you would end up with 2000 statements (1000 originals plus 1000 void statements).

A voided statement does not remove the original statement. Instead, when you call a statement that has been voided, you’ll receive  a 404 error (though in this case we’ll know it’s because we’ve voided the original).

Using Postman to Void a Statement

Voiding statements is easy, but you first need to pull up the Statement ID using an API tool such as Postman (check out this post if you’re not sure how to search for a Statement).

If you’re not sure what things should look like, you may wish to follow this video walkthrough:

Once you’ve got your statement, set your objectType to “StatementRef”, and your verb to “voided”, so that it looks something like this (with your statement ID in the object’s ID field instead):

{

“actor”: {

“objectType”: “Agent”,

“name”: “John Smith”,

“account”: {

“name”: “123”,

“homePage”: “https://www.example.com/users/”

}

},

“verb”: {

“id”: “https://adlnet.gov/expapi/verbs/voided”,

“display”: {

“en-GB”: “voided”

}

},

“object”: {

“objectType”: “StatementRef”,

“id”: “05a8c06c-0b7e-4003-8d02-9a07998b8907”

}

}

And that’s it! It really is as simple as knowing the Statement ID(s) that you want to void and then remembering to repost the statement(s) if you need to change something in the record, or later decide that it is valid.

For more practical tips and advice about the xAPI, download our Technology Managers Guide to xAPI

blank
Ryan Smith
Software Development Team Lead

Starting as a placement student in 2014, Ryan re-joined the Learning Locker team after graduating from Oxford Brookes University where he won the John Birch prize for the highest grade average in the University.

From his minimalist desk, Ryan leads the Learning Locker team and consults with people on all things xAPI to conscientiously craft products and services that sustain and evolve training and performance.

When he’s not swimming or injuring himself on the cricket field, Ryan enjoys playing funny (and usually inappropriate) games with his family.

View more from Ryan Smith
blank
Read more about Learning Pool
Visit our Learn and Connect section

Get a free demo

Get in touch to find out how we can help

Start your learning journey

Get started by telling us what you need and one of our team will be in touch very soon.