How to Void an xAPI Statement
June 30, 2016
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
Got a learning problem to solve?
Get in touch to discover how we can help
