Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Tweaks to dbt and xAPI extending docs #229

Merged
merged 4 commits into from
Jun 27, 2024
Merged
Show file tree
Hide file tree
Changes from 3 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 7 additions & 4 deletions docs/how-tos/dbt_extensions.rst
Original file line number Diff line number Diff line change
Expand Up @@ -119,8 +119,8 @@ Our new model calculates the average number of attempts made by users on each pr
)
group by problem_id

Next, make sure your model is configured in the ``db_project.yml``. If you forget this step, dbt will warn you when
running your package.
Next, make sure your model is configured, for example in the ``db_project.yml``. If you forget this step, dbt will warn
you when running your package.

.. code-block:: yaml

Expand All @@ -130,7 +130,7 @@ running your package.
+materialized: view


See `About dbt models`_ to learn more.
See `Configure dbt models`_ to learn more.

Step 5. Add tests
=================
Expand Down Expand Up @@ -207,7 +207,7 @@ You may need to repeat steps 4-6 a few times to resolve any warnings or errors t
Don't forget to push your changes to your repo before running the tutor dbt command: it fetches a clean copy of your
configured package repo + branch each time it runs.

See `dbt debugging`_ for more information on how to debug issues with your package.
See `dbt debugging`_ and `The missing guide to debug() in dbt`_ for more information on how to debug issues with your package.


References
Expand All @@ -219,6 +219,7 @@ References
* `Writing data tests`_: dbt's guide to writing package tests
* `dbt commands`_: list of all dbt commands
* `dbt debugging`_: guide for debugging issues with dbt
* `The missing guide to debug() in dbt`_: detailed advice for debugging issues with dbt
* `aspects-dbt`_: Aspects' dbt package
* `aspects-dbt-example`_: the demo custom dbt package used in this tutorial.
* `eduNEXT/dbt-aspects-unidigital`_: a real custom dbt package running in production Aspects
Expand All @@ -229,6 +230,7 @@ References
.. _aspects-dbt requirements.txt: https://github.com/openedx/aspects-dbt/blob/main/requirements.txt
.. _About dbt init: https://docs.getdbt.com/reference/commands/init
.. _About dbt models: https://docs.getdbt.com/docs/build/models
.. _Configure dbt models: https://docs.getdbt.com/reference/model-configs
.. _Best practice guides: https://docs.getdbt.com/best-practices
.. _dbt commands: https://docs.getdbt.com/reference/dbt-commands
.. _dbt debugging: https://docs.getdbt.com/guides/debug-errors
Expand All @@ -238,3 +240,4 @@ References
.. _Install dbt: https://docs.getdbt.com/docs/core/installation-overview
.. _Writing data tests: https://docs.getdbt.com/best-practices/writing-custom-generic-tests
.. _tutor-contrib-aspects plugin.py: https://github.com/openedx/tutor-contrib-aspects/blob/main/tutoraspects/plugin.py
.. _The missing guide to debug() in dbt: https://docs.getdbt.com/blog/guide-to-jinja-debug
25 changes: 14 additions & 11 deletions docs/how-tos/xapi_transforms.rst
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ Transforming a new event
Events emitted by ``openedx`` packages are transformed by `event-routing-backends`_ (ERB), a Django plugin which Aspects installs on Open edX.

Transformers for events emitted by non-openedx packages should be stored close to the code that produces the events, and registered using decorators provided by `event-routing-backends`_. We
will use OpenCraft's `completion aggregator`_ as the example for this tutorial, building on events emitted by `pr#173`_.
will use OpenCraft's `completion aggregator`_ as the example for this tutorial, specifically code added `pr#205`_.

xAPI Schema
===========
Expand Down Expand Up @@ -135,14 +135,14 @@ Result
Some Open edX events use a "result" stanza that communicates information about the effect that this event had. For example, "problem check" events record whether the problem was answered
correctly, and what score the actor received.

For these completion "progressed" events, we would want to store:
For these completion "progressed" events, we would want to store the percent completed, so we use an extension:

.. code-block:: json

{
"completion": false,
"score": {
"scaled": ".45"
"extensions": {
"https://w3id.org/xapi/cmi5/result/extensions/progress": "45"
}
}

Expand All @@ -151,7 +151,7 @@ Implementation
==============

Once the xAPI event schema is settled, the implementation should be pretty straightforward using
`event-routing-backends`_ and `TinCan`_.
`event-routing-backends`_ and `TinCan`_. See `pr#205`_ for full example code.

#. Create a new transformer class that extends `XApiTransformer`_.
#. Implement the ``get_verb`` method, returning your chosen verb URI and its short name.
Expand All @@ -160,10 +160,13 @@ Once the xAPI event schema is settled, the implementation should be pretty strai
For example, to customize the context activities for your event, override ``get_context_activities``.

Use the built-in transformer method ``get_data`` to parse and return data from the original tracking event.
#. Register your transformer class using the registry decorator.
#. Register your transformer class using the ``XApiTransformersRegistry.registry`` decorator.

Use the raw tracking event's ``type`` as the parameter to ensure this class is used to transform those type of events.

#. Write data transform tests by subclassing `XApiTransformersFixturesTestMixin` and adding ``raw`` JSON and ``expected``
xAPI event fixture data.


.. warning::
There can only be one registered xAPI transformer class per tracking event ``type``.
Expand Down Expand Up @@ -223,13 +226,13 @@ Here is the full code for the new transformer described in this tutorial.

# Register subclasses for each individual event type

@XApiTransformersRegistry.register("edx.completion_aggregator.progress.chapter")
@XApiTransformersRegistry.register("edx.completion_aggregator.progress.sequential")
@XApiTransformersRegistry.register("edx.completion_aggregator.progress.vertical")
@XApiTransformersRegistry.register("openedx.completion_aggregator.progress.chapter")
@XApiTransformersRegistry.register("openedx.completion_aggregator.progress.sequential")
@XApiTransformersRegistry.register("openedx.completion_aggregator.progress.vertical")
class ModuleProgressTransformer
object_type = "http://adlnet.gov/expapi/activities/module"

@XApiTransformersRegistry.register("edx.completion_aggregator.progress.course")
@XApiTransformersRegistry.register("openedx.completion_aggregator.progress.course")
class CourseProgressTransformer
object_type = "http://adlnet.gov/expapi/activities/course"

Expand Down Expand Up @@ -309,7 +312,7 @@ References
.. _ERB's xAPI filters: https://event-routing-backends.readthedocs.io/en/latest/getting_started.html#openedx-filters
.. _external ID: https://github.com/openedx/edx-platform/blob/master/openedx/core/djangoapps/external_user_ids/docs/decisions/0001-externalid.rst
.. _openedx-filters: https://github.com/openedx/openedx-filters
.. _pr#173: https://github.com/open-craft/openedx-completion-aggregator/pull/173
.. _pr#205: https://github.com/open-craft/openedx-completion-aggregator/pull/205
.. _progressed: http://adlnet.gov/expapi/verbs/progressed
.. _TinCan: https://github.com/RusticiSoftware/TinCanPython
.. _xAPI profiles: https://profiles.adlnet.gov/
Expand Down