VA-1542 Add 'reset' xAPI event

[wwalmnes-d2l]

No description provided.

[otacke]

@wwalmnes-d2l Are content types supposed to trigger the reset event when they are reset from now on?

[wwalmnes-d2l]

@otacke, it is not completely landed yet, but we will discuss this during our meeting today.

Just to give you some background information, since you probably don't have access to this issue on JIRA. In e.g. QuestionSet we want to be able to update the navigation status (the dots) immediately when a user has answered/reset. On production today, this is updated only when moving to the next/previous question. Before this issue/PR on redesign only when the user answered did the navigation status update and not when doing reset, giving an inconsistent behavior.
Originally, I was thinking of just creating a customEvent and dispatching it on the DOM node, but I asked Thomas if this would be the correct way to do it in H5P. He recommended that we add a "reset" event and use the EventDispatcher with xAPI similar to "answered" event.
So ideally we would keep an updated list of all verbs we're using and perhaps update the Question contract.
For now, we would either have all the content types that extend question trigger this event, or perhaps that question itself triggers it.

Since you are much more familiar with H5P than me, do you see any problems or concerns with this?

[otacke]

@wwalmnes-d2l Yes, can't access anything but the HFP tickets on JIRA.

In general, I think xAPI is underused, so no problem with that change :-D Just wanted to know if I have to touch 30+ content types to support it.

H5P.Question won't be able to handle this unless you amend the API or introduce some best guess, because addButton does not know about the button's true function. You could e.g. assume that when the retry icon is requested, that this is indicated a callback to reset the content type - but I fear that icon could make sense in other contexts, too, and people might use it for different things.

You can't intercept calls to resetTask in the contract either, so you cannot always know about a reset that could be called by 3rd party code. And only having it for Question type content types feels odd, too.

You could use a custom event, H5P core already triggers some events such as initialized or datainclipboard via the ExternalDispatcher as well. But since knowing about a reset makes sense for learning analytics, too, xAPI feels like a better and nice choice.

The allowedXAPIVerbs constant is not thaaat important, IMHO. It's only used by setVerb (which you do not need to use) and if you need any other verb, you can do so by setting the verb on the xAPIEvent object directly. Have done that myself before.

[otacke]

@wwalmnes-d2l One more thing ... Coming up after my next appointment.

[otacke]

@wwalmnes-d2l "And now the continuation ..."

TL;DR

• The allowedXAPIVerbs constant does not make sense in its current form (the original purpose seems to have got lost).
• H5P core should not report bogus IRIs for xAPI verbs.
• Own verbs/extensions should be documented on the web.
• Yes, that's not the scope of VA-1542, but should be addressed IMHO. And while we're at it ... Use en instead of en-US as xAPI language tag #93

I don't know how familiar you are with xAPI, so I'll elaborate a little further on that topic (see e.g. https://github.com/adlnet/xAPI-Spec/blob/master/xAPI-Data.md#part-two-experience-api-data for quite a good technical overview).

xAPI is an extendable framework. Boiled down a lot, it can be used to transfer information about an "experience" following the schema "actor verb object" - someone did somehing to something. That actor could be a student, the verb could be "completed", the object could be some specific exercise. There's a lot more detail, but that is the essence. A learning record store would keep track of these statements and thus keep track of what the actor did - his or her "experience".

Now about those verbs.

A

There is no predefined set of allowed verbs anywhere. xAPI is not a standard, but as mentioned, an extendable framework. Learning designers could come up with all sorts of verbs that could be useful in some context to document the users' experience. It could be "clicked" if you wanted to register mouse clicks, it could be "paused" if you wanted document that a video was paused, it could be "registered" if a participant registered for a seminar, etc.

That's the reason why that allowedXAPIVerbs constant feels odd to me. There may have been a reason for introducing it (ST did over 10 years ago in the early stages of H5P core, 5922786), but that reason may remain one of the great mysteries of H5P's past. To me, it does not make sense to restrict the verbs. But ...

B

There is more to verbs. As mentioned, there is no fixed valid set of them in xAPI. It's a learning designer's (or software developer's) job to come up with a use case and a reasonable verb. Now, in different contexts, a verb may be ambiguous. Using it may mean x in context a or y in context b. The difference might be a nuance, but it could also be more complex.

That is why transmitting a verb in xAPI does not merely consist of a string such as completed which you normally would in an event. It's not a name. In xAPI, that "display" name is even optional. The crucial bit is an IRI, an Internationalized Resource Identifier. Think of it as a URI/URL (for a reason, bear with me I'll get to that in a second).

That IRI is supposed to clearly identify who coined that verb in order to allow distinguishing between different meanings that different creator may associate with the verb. "completed" in Moodle might mean something different that in H5P, for instance. Now, that IRI usually is not a UUID or something similar, but a URL. On the one hand, they allow to clearly convey who coined the verb (e.g. "h5p.org" vs. "moodle.org" in the domain). More importantly, they allow to follow that URL to a resource that can explain in more detail what the verb is supposed to mean, how it should be used, etc.

And now to the important bit for H5P core. The setVerb function builds that URL from the verb that is passed as the function argument:

  'id': 'http://adlnet.gov/expapi/verbs/' + verb,

(https://github.com/h5p/h5p-php-library/blob/master/js/h5p-x-api-event.js#L74C7-L74C54)

In other words, if you are not careful, H5P core hallucinates IRIs for verbs that do not exist. That may in fact have been the original purpose of the allowedXAPIVerbs constant: to ensure that the IRIs are valid and refer to a verb that actually is documented somewhere. I am quite sure though that this is already broken, as I don't think that accessed-reuse and the resulting http://adlnet.gov/expapi/verbs/accessed-reuse is defined. I don't mean the URL itself. Something like http://adlnet.gov/expapi/verbs/completed which is completely legit and defined (used to be https://web.archive.org/web/20130501074154/http://adlnet.gov/expapi/verbs/completed) also does not resolve anymore.

My point is that H5P core should not knowingly create bogus IRIs for xAPI statements as it now does, but either build IRIs that belong to an existing xAPI definition (for verbs) that fits, see e.g. https://registry.tincanapi.com/#home/verbs or https://xapi.elearn.rwth-aachen.de/) or to use one that specifically relates to h5p, e.g. http://h5p.org/xapi/verbs/reset including a page under that URL with detail information.

Same goes for extensions by the way (cmp. e.g. https://h5p.org/x-api/h5p-reporting-version or https://snordian.de/xapi/extension/time-left).

[icc]

I'm not sure on the history here, but it could have been to be compatible with another system at the time, or it might just have been to control or prevents devs from adding new verbs without properly defining them somewhere.
I do think we had a few custom cases where we extended the list to allow for additional words.

[otacke]

@icc Great to see you joining here.

Yes, there are those verbs for action bar events (https://github.com/h5p/h5p-php-library/blob/master/js/h5p-x-api-event.js#L325-L330). Those have been labeled as custom, but they lead to building IRIs that are not specified.

The original definition of allowedXAPIVerbs ensured that building http://adlnet.gov/expapi/verbs/${verb} lead to an IRI that was a real specification (cmp. what's listed at https://registry.tincanapi.com/#home/verbs). The custom verbs for the action bar create bogus IRIs, and so will reset. IMHO, H5P Group should introduce h5p.org IRIs as they did for extensions, e.g. https://h5p.org/x-api/h5p-reporting-version (that URL even leads to a page with details as it's supposed to).

[wwalmnes-d2l]

@otacke Thank you for taking the time to explain xAPI a bit to me. I'll check out the resources you shared :). I know we would like to know about how the user interacts with the content, so like you said, having reset under xAPI would make sense.

I agree it would be better if we did this correctly and would provide (real) IRIs for new verbs we're introducing or reference existing ones.

We decided in our meeting that we did not want to introduce this reset event now (as part of the redesign work). We should get a better overview of our usage of xAPI first and also map out other events we would like to track and do this as a separate project.