Merge pull request #114 from openedx/jill/howto-xapi-transforms

docs: adds How To do xAPI Transforms

docs/concepts/xapi_concepts.rst

@@ -4,47 +4,113 @@ xAPI
 ****
 
 Introduction
-###################
+############
 
-xAPI, also known as the Experience API or Tin Can API, is a specification for capturing
+xAPI, also known as the `Experience API`_ or Tin Can API, is a specification for capturing
 and tracking learning experiences in a wide range of contexts. It is an e-learning
 standard that allows organizations to gather data about learner activities and interactions
 across various platforms and devices. xAPI provides a flexible and comprehensive
 framework for collecting, storing, and analyzing learning data, enabling a deeper
 understanding of learners' experiences and performance.
 
-Components of xAPI
-###################
+Together, these components form the foundation of the xAPI ecosystem, enabling
+the tracking and analysis of learner activities and experiences beyond traditional
+learning management systems. The flexibility and interoperability of xAPI make it
+an ideal solution for organizations looking to gain deeper insights into their
+learners' performance and behavior.
 
-The xAPI specification consists of three key components:
+xAPI Schema
+###########
 
-.. _actor_concept:
+While the components of an :ref:`xapi_statement` are well specified, the actual detailed format or "schema" used for
+each type of xAPI event is up to us to decide, as users of xAPI.
 
-Actor
-~~~~~
-In xAPI, an actor represents an entity that interacts with the learning system.
-It can be a learner, instructor, system administrator, or any other agent
-involved in the learning process. Actors are identified using a unique identifier,
-such as an email address or username.
+See :ref:`xapi_transforms` for information on how the schemas are built.
+
+.. _xapi_statement:
+
+xAPI Statement
+##############
 
-Statement
-~~~~~~~~~
 A statement, also referred to as an "xAPI statement" or "verb-object statement,"
 is the core building block of xAPI. It captures a specific learning activity
 or experience in a structured format. A statement consists of three essential
 elements: the actor who performed the action, the verb that describes the action,
 and the object representing the target or learning experience.
 
+An xAPI statement can be expressed briefly as:
+
+  **Actor** **Verbed** an **Object** (within **Context**).
+
+ID
+~~
+
+Each xAPI event emitted by Open edX will contain a `Universally Unique Identifier`_ (UUID)
+which is generated from the event actor, timestamp, verb, and child event ID (if present).
+This ID is used to de-duplicate events, for example when re-processing old tracking logs.
+
+.. _actor_concept:
+
+Actor
+~~~~~
+In xAPI, an actor represents an entity that interacts with the learning system.
+It can be a learner, instructor, system administrator, or any other agent
+involved in the learning process.
+
+By default, actors in Aspects are uniquely identified using a platform-generated
+``external_id`` which helps keep event data anonymous. Aspects can link this ``external_id``
+back to a username or email address where individual identities are needed. See
+:ref:`changing_actor_identifier` for more options.
+
+Verb
+~~~~
+Verbs in xAPI are URIs paired with short, translated, human-friendly labels. Verbs
+should be in past tense, idenoting that the action has already been performed.
+
+There are many verbs used in Aspects events, for example:  completed, progressed,
+registered, unregistered, passed, failed, voted, asked, reported, attempted, completed,
+earned, etc. Each verb has its own specific purpose and target Object.
+
+Object
+~~~~~~
+xAPI objects consist of a unique identifier and a "definition" stanza, which describes the
+object of the actor's verb.
+
+Most objects in Aspects xAPI events are of type "Course", "Discussion", or "Activity". For
+example, learners may enrol or unenrol from a Course, post in a Discussion, or complete an
+assignment Activity.
+
+Context
+~~~~~~~
+
+xAPI events generally occur within some learning context, and so this stanza provides a
+place to record important meta information about the event. Context stanzas may contain
+"extension" fields which allow arbitrary data to be attached to an event.
+
+Aspects uses context to provide enclosing course data where the object is an activity or
+discussion, or "context activities" like a problem block which wraps several questions.
+Aspects also uses an "extension" to store the version of the xAPI transforms that were
+applied to the event.
+
 Learning Record Store (LRS)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+###########################
+
 The Learning Record Store serves as the repository for storing and retrieving xAPI
 statements. It is a database or storage system that receives and securely stores
 the statements generated by learning activities. The LRS enables the collection
 and organization of learning data from various sources, allowing for robust
-analysis and reporting of learner experiences.
+analysis and reporting of learner experiences. An LRS may also be used to recommend
+content to learners based on previous performance or interest.
 
-Together, these components form the foundation of the xAPI ecosystem, enabling
-the tracking and analysis of learner activities and experiences beyond traditional
-learning management systems. The flexibility and interoperability of xAPI make it
-an ideal solution for organizations looking to gain deeper insights into their
-learners' performance and behavior.
+References
+##########
+
+* `OEP-26`_: xAPI Real-time events
+* `Experience API`_: specification for xAPI
+* `xAPI Statements 101`_: guide to xAPI statements and their components
+
+
+.. _OEP-26: https://open-edx-proposals.readthedocs.io/en/latest/architectural-decisions/oep-0026/xapi-realtime-events.html
+.. _Experience API: https://xapi.com/specification/
+.. _xAPI Statements 101: https://xapi.com/statements-101/
+.. _Universally Unique Identifier: https://en.wikipedia.org/wiki/Universally_unique_identifier

docs/how-tos/changing_actor_identifier.rst

@@ -1,3 +1,5 @@
+.. _changing_actor_identifier:
+
 Changing the xAPI actor identifier
 ##################################
 

docs/how-tos/dbt_extensions.rst

@@ -64,7 +64,7 @@ Update the following Tutor variables to use your package instead of the Aspects
 Once your package is configured in Tutor, you can run dbt commands directly on your deployment; run ``tutor [dev|local] do dbt --help`` for details.
 
 References
-**********
+##########
 
 * `Building dbt packages`_: dbt's guide to building packages
 * `Writing data tests`_: dbt's guide to writing package tests

docs/how-tos/index.rst

@@ -15,5 +15,6 @@ How-Tos
    Superset custom roles <superset_roles>
    Clickhouse extra SQL <clickhouse_sql>
    Connect to external Clickhouse database <remote_clickhouse>
-   Extending DBT <dbt_extensions>
+   Extending dbt <dbt_extensions>
    Run Aspects in a ClickHouse cluster <clickhouse_cluster>
+   xAPI Transforms <xapi_transforms>