docs: adds How To do xAPI Transforms

[pomegranited]

Description

Adds a "how to" document for creating new xAPI Transforms.

Supporting information

Closes #75

[openedx-webhooks]

Thanks for the pull request, @pomegranited! Please note that it may take us up to several weeks or months to complete a review and merge your PR.

Feel free to add as much of the following information to the ticket as you can:

• supporting documentation
• Open edX discussion forum threads
• timeline information ("this must be merged by XX date", and why that is)
• partner information ("this is a course on edx.org")
• any other information that can help Product understand the context for the PR

All technical communication about the code itself will be done via the GitHub pull request interface. As a reminder, our process documentation is here.

Please let us know once your PR is ready for our review and all tests are green.

[Ian2012]

Thanks for this documentation

[bmtcril]

Couple of nits and comments, otherwise this looks great. Couple of last thoughts:

• Maybe you could throw in a reference to the ERB filters somewhere, so that people know they don't necessarily have to create their own transforms if they only want to override some default behavior.
• Related, it's probably also worth noting that there can be only one registered xapi transformer per tracking log event name, so it is possible to completely override the default transforms, and also may be an unintended side effect of writing your own.

[bmtcril]

nit: Couple of typos in this sentence

[pomegranited]

Fixed: https://docsopenedxorg--114.org.readthedocs.build/projects/openedx-aspects/en/114/concepts/xapi_concepts.html#verb

[bmtcril]

Might want to link in this doc: changing_actor_identifier somewhere here as it has some important specifics.

[pomegranited]

Done: https://docsopenedxorg--114.org.readthedocs.build/projects/openedx-aspects/en/114/concepts/xapi_concepts.html#actor

[bmtcril]

We should probably discourage people from reusing verbs that are already in use in ERB whenever possible, as we do a lot of processing based on the verb and it will potentially lead to confusion and maybe performance issues to overload terms.

[Ian2012]

Talking about it, we should also update our filters to not only filter events based on the verb but also the object type and even the context activities. Mainly to allow developers to use the same verb and don't trigger any error on the downstream tables.

For the completion-aggregator and with internal libraries @andrey-canon had a lot of issues with the completion events because he was using the same verb

[pomegranited]

Talking about it, we should also update our filters to not only filter events based on the verb but also the object type and even the context activities.

That's a good point.

[pomegranited]

I've updated this PR to discourage verb re-use: https://docsopenedxorg--114.org.readthedocs.build/projects/openedx-aspects/en/114/how-tos/xapi_transforms.html#verb

[pomegranited]

@bmtcril

Maybe you could throw in a reference to the ERB filters somewhere, so that people know they don't necessarily have to create their own transforms if they only want to override some default behavior.

Yep, happy to do that.

But I'm having trouble figuring out how these filters work.. does the filter_type passed to the decorator need to match the key used when registering the transformer class? For example, is this how to override CompletionCreatedTransformer.get_object?

@openedx_filter(filter_type="edx.completion.block_completion.changed")
def get_object(self):
   ...

[bmtcril]

@pomegranited I believe the filter_type is one of these: https://event-routing-backends.readthedocs.io/en/latest/getting_started.html#xapi-filters

[Ian2012]

@pomegranited Brian is right, you need to use one of those filters. Here are some examples for the filters: https://github.com/eduNEXT/eox-nelp/blob/master/eox_nelp/openedx_filters/xapi/filters.py

[pomegranited]

@Ian2012 @bmtcril Ah cool, thank you for these pointers.

But xAPI filters doesn't seem to be a complete list? e.g. XApiContextFilter uses event_routing_backends.processors.xapi.transformer.xapi_transformer.get_context, which is not on that list. So does that actually mean we can override any method on any transformer?

[andrey-canon]

@Ian2012 @bmtcril Ah cool, thank you for these pointers.

But xAPI filters doesn't seem to be a complete list? e.g. XApiContextFilter uses event_routing_backends.processors.xapi.transformer.xapi_transformer.get_context, which is not on that list. So does that actually mean we can override any method on any transformer?

@pomegranited basically that is not in the list because that is not in the master code, the library that you are checking depends on a specific version of event-routing-backends that included that filter in this pr however I haven't had enough time to open the upstream pr

[pomegranited]

@andrey-canon Ahh... I understand now, thank you! I've updated the code example to use a filter that's already in upstream: 123930a

@bmtcril could you take another look at this PR when you get a chance?

[bmtcril]

LGTM thanks!

[openedx-webhooks]

@pomegranited 🎉 Your pull request was merged! Please take a moment to answer a two question survey so we can improve your experience in the future.