Was it the butler, or Mrs Brown with the Candlestick in the Conservatory? Choosing the actor of your xAPI statement can be a bit of a puzzle…
Brian Miller’s deep dive into Agents is a great introduction into the technical structure of the Agent object and overview of the various places an agent can sit within the statement: as the actor, as the object, or as the team or instructor property of the context. This is a must-read for developers implementing xAPI.
As designers, we’re presented with a slightly different question: who is the Agent that will be the subject of our statement? In many cases the answer is straightforward— the Agent is whoever did the thing:
Bob completed this course
Sue watched that video
But what if there’s more than one person involved in the experience? Did Sue mentor Bob or was Bob mentored by Sue? Did the manager observe the worker or was the worker observed by the manager? How do we choose? This is exactly the question Jessie Chuang asked on the xAPI Google Groups, so let’s dive into the answer!
On one level, it often doesn’t really matter which way round (and where) the Agents appear in the statement. When queried for statements, the LRS will return any statements where the matching Agent is either the “actor” or the “object”. It’s also possible to ask the LRS to filter more broadly, searching the “instructor”, “team” and “authority” properties too. So long as your reporting tool understands the verbs and statement structure you’ve used, it’ll have no trouble finding statements about a particular Agent regardless of where they appear in the statement.
Be consistent
The key is consistency. The report needs to understand the statement structure, so make sure the statements you want to feed into a report all follow the same structure. The profiles and recipes in The Registry are designed to provide that consistency and guide you on how to structure your statements in a particular application of xAPI. If a recipe exists for the experience you’re tracking, then you should follow that recipe; if not, then you should create one. We’d be more than happy to help you do that.
Let’s assume for this blog that the recipe you need doesn’t already exist and you need to create one. We’ll take the example of a mentoring scenario where Sue is the mentor and Bob is the mentee. Their mentoring is related to a competency within Bob’s job role: ‘Statement Crafting’. How do we decide whether Bob mentored Sue or Sue mentored Bob? Or was Bob mentored on the topic of ‘Statement Crafting’ with Sue as the instructor?
Choose an actor
As a general rule of thumb, the “actor” of the statement is the Agent in the statement who you care most about. Statements rarely come on their own, and chances are you’ve got a stream of statements about a single Agent—normally the learner. In that case, the “actor” of your statement should be the same as in all the other statements in the stream.
In some cases both Agents will be important. We might be interested both in Sue’s mentoring and Bob’s mentorship and have streams of statements relating to both. In this case, consider issuing two statements about the experience: one for Bob and one for Sue. These can be linked using the “statement” and “registration” properties of the statement’s “context”.
Choose an object
With the “actor” selected, the next step is to choose the “object”. Should the “object” be the secondary Agent, or an Activity? In our example, if Bob is the “actor”, should Sue be the “object” or should the “object” be the ‘Statement Crafting’ competency?
Again, this is a question of what’s important? Do you care most that Bob was mentored by Sue, or that he was mentored about ‘Statement Crafting’? You should pick the most important element as the “object” and store the other in the statement “context” either as the “instructor” or as one of the Context Activities.
If Sue was the “actor” of the statement then we really need to have Bob as the “object” (i.e. Sue mentored Bob) even if the topic of the mentoring is more significant than who was mentored. xAPI statements have no standard property for “student” like they do for “instructor”, so the “object” is the only sensible place for the learner to go if the “actor” spot is already filled. The topic of the mentoring can sit as one of the Context Activities.
It’s worth noting that your choice of “verb” should come after choosing the “actor” and “object”. Once you’ve chosen your “actor” and “object”, you should go back and choose or create a Verb to fit.
But don’t forget consistency!
As I mentioned above, consistency is the most important thing and if an established recipe exists that goes against the guidelines above, you should follow that recipe instead. Consistency is the key to ensuring our tools work well with one another and reporting tools can access the information wherever it sits in the statement.
The next step in designing your agents is choosing which identifier to use, but I’ll leave that topic for another time. For now, if you have questions please drop me an email or a tweet.
Now, go design statements!
