doc: initiate Badges documentation

raccoongang · Nov 30, 2023 · f9a84af · f9a84af
1 parent 40a4d2a
commit f9a84af
Show file tree

Hide file tree

Showing 12 changed files with 553 additions and 0 deletions.
diff --git a/docs/badges/_puml/badges-flow-sequence.puml b/docs/badges/_puml/badges-flow-sequence.puml
@@ -0,0 +1,58 @@
+@startuml name "Open edX Badges"
+
+title "Generic case (sequence diagram)"
+
+autonumber
+
+actor           Learner as learner
+actor           Instructor as instructor
+box "Open edX"
+participant     "EventBus" as ebus
+participant     "LMS" as lms
+participant     "Studio" as cms
+participant     "Credentials IDA\n(badges app)" as credentials
+participant     "Projection\n backend\n (Credly)" as backend
+end box
+box "Badge projection services"
+participant     "Credly" as credly
+participant     "Other" as other
+end box
+actor           Admin as admin
+
+== Projection service setup ==
+
+admin -> credly : Creates Organization
+admin -> credly : Creates a badge A (template)
+admin -> credly : Creates a badge B (template)
+
+
+== Open edX Configuration ==
+
+rnote over credentials : Implements\nBadge(AbstractCredential)
+rnote over backend : Implements\nCredlyBadge
+
+admin -> backend : Creates backend configuration (API)\n(Open edX installation <=> Credly Org?)
+rnote over credentials,credly : Shared credentials/OAuth2/...?
+
+credentials -> credly : Pulls available (Org) badge templates
+backend <-> credly : Uses webhook to keep\n badge templates in sync?
+rnote over backend
+    - CredlyBadge(A) is created
+    - CredlyBadge(B) is created
+endrnote
+
+...
+
+== Usage ==
+
+learner -> lms : Enrolls to a course
+
+
+
+learner -> lms : Completes a course X
+lms -> ebus : Emits <course-completed>\ncontext={user+course}
+ebus -> credentials : Emits <course-completed>\ncontext={user+course}
+
+
+
+@enduml
diff --git a/docs/badges/_puml/credly-integration-sequence.puml b/docs/badges/_puml/credly-integration-sequence.puml
@@ -0,0 +1,58 @@
+@startuml name "Open edX Badges"
+
+title "Generic case (sequence diagram)"
+
+autonumber
+
+actor           Learner as learner
+actor           Instructor as instructor
+box "Open edX"
+participant     "EventBus" as ebus
+participant     "LMS" as lms
+participant     "Studio" as cms
+participant     "Credentials IDA\n(badges app)" as credentials
+participant     "Projection\n backend\n (Credly)" as backend
+end box
+box "Badge projection services"
+participant     "Credly" as credly
+participant     "Other" as other
+end box
+actor           Admin as admin
+
+== Projection service setup ==
+
+admin -> credly : Creates Organization
+admin -> credly : Creates a badge A (template)
+admin -> credly : Creates a badge B (template)
+
+
+== Open edX Configuration ==
+
+rnote over credentials : Implements\nBadge(AbstractCredential)
+rnote over backend : Implements\nCredlyBadge
+
+admin -> backend : Creates backend configuration (API)\n(Open edX installation <=> Credly Org?)
+rnote over credentials,credly : Shared credentials/OAuth2/...?
+
+credentials -> credly : Pulls available (Org) badge templates
+backend <-> credly : Uses webhook to keep\n badge templates in sync?
+rnote over backend
+    - CredlyBadge(A) is created
+    - CredlyBadge(B) is created
+endrnote
+
+...
+
+== Usage ==
+
+learner -> lms : Enrolls to a course
+
+
+
+learner -> lms : Completes a course X
+lms -> ebus : Emits <course-completed>\ncontext={user+course}
+ebus -> credentials : Emits <course-completed>\ncontext={user+course}
+
+
+
+@enduml
diff --git a/docs/badges/collection.rst b/docs/badges/collection.rst
@@ -0,0 +1,25 @@
+Collection
+==========
+
+**Collection** is a process of:
+
+- learners' `fulfillments` update subscription
+- badge requirements completion analysis
+- completed badge awarding
+
+Fulfillments subscription
+-------------------------
+
+- checks if updated Fulfillment became *completed*
+
+
+Badge completion analysis
+-------------------------
+
+- checks if related badge is completed (all related requirements are fulfilled)
+
+Badge awarding
+--------------
+
+At some point...
+TBD
diff --git a/docs/badges/configuration.rst b/docs/badges/configuration.rst
@@ -0,0 +1,90 @@
+Configuration
+=============
+
+Badges feature configuration includes:
+
+- badges management
+- requirements setup
+
+Badges management
+-----------------
+
+Badges management includes the following life-cycle stages or maintenance activities:
+
+- badges creation
+- badges activation (deactivation)
+- badges editing
+- badges archiving
+- badges configuration
+- badges revocation?
+- badges reconciliation?
+
+Creation
+~~~~~~~~
+
+Before being used a badge must be created.
+Each `badge`_ has at least its basic properties:
+
+- unique identifier
+- label (verbose name)
+- icon(image)
+
+.. note::
+    It is expected that `distribution backends`_ will extend basic properties set with their own set.
+
+Activation
+~~~~~~~~~~
+
+A Badge is created as inactive, so system won't use it before explicit activation.
+
+Editing
+~~~~~~~
+
+Badge can be modified in inactive status only. Unique identifier cannot be changed.
+
+Archiving
+~~~~~~~~~
+
+Badge never gets removed, instead it should be *archived*, so system stops using it (but already issued badges are still there).
+
+Configuration
+~~~~~~~~~~~~~
+
+To be activated a badge must be configured.
+Configuration includes `requirements setup`_.
+
+System allows badges management via:
+
+- **Credentials admin interface**
+- internal API?
+    - MFE?
+    - CMS?
+- public events?
+    - CMS?
+- external hooks?
+
+
+Requirements setup
+------------------
+
+Each badge must be configured with *requirements* before its activation.
+
+    **Requirement** is a rule which must be *fulfilled* by learners for associated badge to be earned.
+
+A badge must have at least 1 `requirement`_ associated with it.
+A badge may have multiple requirements.
+
+.. note::
+    **Requirement** describes **Badge** <requirement> **Event** connection.
+
+Requirements allow to setup the following rules:
+
+- **a single event of a given type**
+- a repetitive event of a given type (not implemented)
+- events combination of different types (not implemented)
+- limited in time range combination of events (not implemented)
+
+.. _badge: details.html#badge
+.. _requirement: details.html#requirement
+.. _distribution backends: distribution.html
+.. _requirements setup: configuration.html#requirements-setup
diff --git a/docs/badges/data.rst b/docs/badges/data.rst
@@ -0,0 +1,15 @@
+API
+===
+
+There is a couple of API endpoints that could be implemented:
+
+- Configuration:
+    - available (active) badges - possible to be earned;
+    - requirements for badge;
+    - badge requirements management (external configuration);
+    - ...
+- Learners:
+    - collected (earned) badges for user;
+    - badges in progress for user;
+    - requirements status for user;
+    - ...
diff --git a/docs/badges/details.rst b/docs/badges/details.rst
@@ -0,0 +1,124 @@
+Implementation Details
+======================
+
+Badges feature is implemented as a separate application within the Credentials Open edX service:
+
+        `credentials/apps/badges/`
+
+Data models
+-----------
+
+Badges application maintains a set of data models.
+
+Badge
+~~~~~
+
+**Badge** data model extends `AbstractCredential`. It represents *native* credentials badges
+(additionally see *distribution badges*).
+
+.. code-block:: python
+
+        Badge(AbstractCredential):
+        """
+        Describes badge type.
+        """
+        - uuid
+        - name
+        - icon
+        - status: "inactive" | "active" | "archived"
+
+Requirement
+~~~~~~~~~~~
+
+**Requirement** describes an association between a Badge and an Event.
+
+It carries a *Rule*: **which** event, **how** and **when** must occur.
+Badge can have multiple Requirements.
+
+.. code-block:: python
+
+        Requirement:
+        """
+        Defines a single rule for badge type.
+        """
+        - Badge (relation)
+        - event_type (association)
+        - meta (rules)
+                - times <int> default=1
+                - start <timestamp> optional
+                - end <timestamp> optional
+
+Fulfillment
+~~~~~~~~~~~
+
+**Fulfillment** record is associated with a Learner. It tracks a single Requirement fulfillment for given learner.
+
+.. code-block:: python
+
+        Fulfillment:
+        """
+        Tracks rule fulfillment for user.
+        """
+        - Requirement (relation)
+        - User (relation)
+        - completed: 0 | 1
+        - times: <int>
+
+UserCredential
+~~~~~~~~~~~~~~
+
+Earned badges are `UserCredential` records with a generic relation to the `Badge`.
+
+Badges extend currently present:
+        - program certificates
+        - course certificates
+
+Public events
+-------------
+
+Since badges are always rely on user-specific events.
+
+.. note::
+        Possibly, we need a separate topic with user-events.
+        See: `EVENT_BUS_PRODUCER_CONFIG`
+
+New events
+~~~~~~~~~~
+
+Badges feature relies on already present public events:
+
+- `COURSE_GRADE_NOW_PASSED` should be expressed as public signal (what is a definition for course completion?)
+- TBD
+
+Badges feature introduces new public events:
+
+- `BADGE_AWARDED` event (public signal)
+- `BADGE_REVOKED` event (public signal)
+
+Event Processor
+---------------
+
+**EventProcessor** (EP) is an entity which is responsible for incoming public events processing.
+
+EventProcessor is configurable. `Distribution backends`_ are able to override its implementation.
+
+Badge Collector
+---------------
+
+**BadgeCollector** (BC) is an entity which is responsible for tracking badges progress for learners and awarding already completed badges.
+
+
+Feature sequence diagrams
+-------------------------
+
+Interaction flow happens as follows.
+
+TBD
+
+        <describe steps>
+
+.. image:: ../_static/images/badges-flow-sequence.png
+        :alt: Verifiable Credentials issuance sequence diagram
+
+
+.. _Distribution backends: distribution.html