diff --git a/docs/technical_documentation/how-tos/dbt_extensions.rst b/docs/technical_documentation/how-tos/dbt_extensions.rst index ab254c7..b59a7b0 100644 --- a/docs/technical_documentation/how-tos/dbt_extensions.rst +++ b/docs/technical_documentation/how-tos/dbt_extensions.rst @@ -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 @@ -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 ================= @@ -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 @@ -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 @@ -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 @@ -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 diff --git a/docs/technical_documentation/how-tos/xapi_transforms.rst b/docs/technical_documentation/how-tos/xapi_transforms.rst index b9a3dd8..129350e 100644 --- a/docs/technical_documentation/how-tos/xapi_transforms.rst +++ b/docs/technical_documentation/how-tos/xapi_transforms.rst @@ -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 =========== @@ -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" } } @@ -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. @@ -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``. @@ -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" @@ -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/