doc: describe badges main concepts

docs/badges/collecting.rst

@@ -0,0 +1,54 @@
+Collecting
+==========
+
+**Collecting** is a process of:
+
+- learners' `fulfillments` update subscription
+- badge requirements fulfillment/revocation analysis
+- completed badge awarding
+- badge revocation
+
+Fulfillments subscription
+-------------------------
+
+Configured `Badge Collector`_ is auto-subscribed for any updates in `Fulfillment`_ records.
+
+
+Badge completion analysis
+-------------------------
+
+- Once user's `Fulfillment`_ is updated, Collector tries to figure out if this update made related Requirement fulfilled.
+- (not implemented) Collector emits `BADGE_REQUIREMENT_FULFILLED` signal.
+- If so, Collector goes further and checks all related requirements.
+- If all badge's requirements are fulfilled, there are no obstacles to award the badge, so Collector emits (internal) `BADGE_REQUIREMENTS_COMPLETE` signal.
+
+
+Badge awarding
+--------------
+
+On `BADGE_REQUIREMENTS_COMPLETE` signal:
+
+- awarding handler creates `UserCredential`_ record;
+- emits external event about the badge awarding fact;
+
+
+Badge revocation analysis
+-------------------------
+
+This is an alternative pipeline step for requirements analysis with `revoke` effect set.
+
+- User's `Fulfillment`_ may be updated, so related Requirement stops being fulfilled.
+- Related badge's requirements become not fulfilled, so Collector emits (internal) `BADGE_REQUIREMENTS_NOT_COMPLETE` signal.
+
+Badge revocation
+----------------
+
+On `BADGE_REQUIREMENTS_NOT_COMPLETE` signal:
+
+- revocation handler updates `UserCredential`_ record's status to `revoked`;
+- emits external event about the badge revocation fact;
+
+.. _Badge Processor: details.html#badge-processor
+.. _Badge Collector: details.html#badge-collector
+.. _Fulfillment: details.html#fulfillment
+.. _UserCredential: details.html#usercredential

docs/badges/configuration.rst

@@ -3,35 +3,151 @@ Configuration
 
 Badges feature configuration includes:
 
+- feature configuration
 - badges management
 - requirements setup
+- backends configuration (optional)
+
+
+Feature configuration
+---------------------
+
+Badges are under a feature flag (disabled by default):
+
+.. code-block:: sh
+
+    # credentials settings:
+    ENABLE_BADGES = false
+
+Also the feature has its configuration which may look like this:
+
+.. code-block:: sh
+
+    # credentials settings:
+    BADGES_CONFIG = {
+        "processing": {
+            "processor": "credentials.apps.badges.processing.BadgeProcessor",
+            "events": [
+                "org.openedx.learning.course.grade.passed.v1",
+                "org.openedx.learning.course.grade.failed.v1",
+            ],
+        },
+        "collecting": {
+            "collector": "credentials.apps.badges.collecting.BadgeCollector",
+            "event_bus_topic": "badges",
+            "events": [
+                "org.openedx.learning.badge.awarded.v1",
+                "org.openedx.learning.badge.revoked.v1",
+            ],
+        },
+        "distribution": {
+            "credly": {
+
+            }
+        }
+    }
+
+Configuration consists of 2 parts:
+
+- `processing`_ includes items related to incoming events processing.
+- `collecting`_ includes items related to completed badges collecting.
+
+Incoming Events configuration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The feature explicitly configures list of system events which are taken into account during processing.
+`Badge Processor`_ is auto-connected to listen to those event types.
+
+.. code-block:: sh
+
+    BADGES_CONFIG["processing"]["events"] = [
+        "org.openedx.learning.course.grade.passed.v1",
+        "org.openedx.learning.course.grade.failed.v1",
+        ...
+    ]
+
+Not registered here event types are ignored.
+
+Outgoing Events configuration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Additionally, badges configuration lists event types which must be registered for external emission:
+
+.. code-block:: sh
+
+    BADGES_CONFIG["collecting"]["events"] = [
+        "org.openedx.learning.badge.awarded.v1",
+        "org.openedx.learning.badge.revoked.v1",
+    ]
+
+By default these event types are dynamically auto-registered to EventBus producer in addition to already present in `EVENT_BUS_PRODUCER_CONFIG`.
+
+Badge Processor
+~~~~~~~~~~~~~~~~
+
+For incoming external events processing configuration points to an importable `Badge Processor`_ class definition.
+
+.. code-block:: sh
+
+    BADGES_CONFIG["processing"]["processor"] = "credentials.apps.badges.processing.BadgeProcessor"
+
+Badge Collector
+~~~~~~~~~~~~~~~~
+
+For completed badges configuration points to an importable `Badge Collector`_ class definition.
+
+.. code-block:: sh
+
+    BADGES_CONFIG["collecting"]["collector"] = "credentials.apps.badges.collecting.BadgeCollector"
+
 
 Badges management
 -----------------
 
 Badges management includes the following life-cycle stages or maintenance activities:
 
 - badges creation
+- badges configuration
 - badges activation (deactivation)
 - badges editing
 - badges archiving
-- badges configuration
 - badges revocation?
-- badges reconciliation?
+- badges reconciliation (not implemented)
+
+.. note::
+    System allows badges management via:
+
+    - **Credentials admin interface**
+    - internal API (not implemented)
+        - Credentials UI (Learner Record MFE)
+        - Badges MFE
+        - Studio
 
 Creation
 ~~~~~~~~
 
 Before being used a badge must be created.
 Each `badge`_ has at least its basic properties:
 
-- unique identifier
-- label (verbose name)
+- uuid (unique identifier, auto-generated)
+- name (verbose label - currently, out of localization)
 - icon(image)
 
+    Currently, badges are managed from Credentials service admin interface (Django).
+
+    - enter admin Badges section
+    - add new Badge record
+    - save new badge
+
 .. note::
     It is expected that `distribution backends`_ will extend basic properties set with their own set.
 
+Configuration
+~~~~~~~~~~~~~
+
+To be activated a badge must be configured.
+Configuration includes `requirements setup`_.
+
 Activation
 ~~~~~~~~~~
 
@@ -40,29 +156,13 @@ A Badge is created as inactive, so system won't use it before explicit activatio
 Editing
 ~~~~~~~
 
-Badge can be modified in inactive status only. Unique identifier cannot be changed.
+Badge can be modified in inactive status only. Unique identifier should not 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
 ------------------
@@ -71,20 +171,71 @@ 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.
+A badge must have at least 1 `requirement`_ associated with it, but badge can have multiple requirements.
+
+**Requirement** describes the connection: **Badge** <--requirement--> **Event**.
+
+Use cases
+~~~~~~~~~
+
+Here is a list of possible use cases for requirements to cover (in examples):
 
 .. note::
-    **Requirement** describes **Badge** <requirement> **Event** connection.
+    Currently only 2, 3 use cases are available.
+
+1. Single generic event (e.g. "Profile data completion");
+2. **Single data-agnostic course event** (e.g "Arbitrary course completion");
+3. **Single data-specific course event** (e.g. "Specific course completion");
+4. Repetitive events (e.g. "5 arbitrary courses completions");
+5. Events combination (e.g. "5 specific courses completions")
+6. Frozen combination of events (e.g. "5 specific courses completions in defined order");
+7. Time-ranged event (e.g. "Arbitrary course completion during January 2024");
+8. Badge dependencies (e.g. "Badge A + Badge B = Badge C");
+9. Multiple times same badge earning (e.g. "3 arbitrary course completions make badge earned x3");
+10. Event combination alternatives... (e.g. "Logical `OR` rule sets: Course A OR Course B completion");
+
+Requirement creation
+~~~~~~~~~~~~~~~~~~~~
+
+Given already created Badge, one now should specify business rules for it.
+
+Requirement records are currently managed via Credentials admin interface:
+
+- enter admin Badges section
+- add new Requirement record
+- associate Requirement with a **badge**
+- by default Requirement has `award` **effect** (also see `Revocation setup`_)
+- specify **event type** from the set of available in `BADGES_CONFIG["processing"]["events"]`
+- specify **event data** (for data-specific requirements)
+- **times** default=1 (not processed, repetitive events)
+- **start** is None (not processed, time-ranged events)
+- **end** is None (not processed, time-ranged events)
+- **rule_set** is None (not processed, combination alternatives)
+
+Revocation setup
+~~~~~~~~~~~~~~~~
+
+During badge configuration additional decision must be made: wether the badge should be `revocable` if conditions it requires are not the case anymore.
+
+    **Example: "Course X completion badge"**
+
+    - **Requirement:** the badge is granted when course grade becomes passing.
+    - **Question:** should badge be revoked if course grade becomes NOT passing (for any reason)?
+
+If answer in the example is "yes", we have to setup additional requirement with `revoke` effect, based on corresponding event type. Requirements with `revoke` effect are processed in a special way.
 
-Requirements allow to setup the following rules:
+Backends configuration
+----------------------
 
-- **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)
+Different backends may require their specific additional configuration.
+See `Distribution`_ section for details.
 
 .. _badge: details.html#badge
 .. _requirement: details.html#requirement
+.. _processing: processing.html
+.. _collecting: collecting.html
 .. _distribution backends: distribution.html
 .. _requirements setup: configuration.html#requirements-setup
+.. _Revocation setup: configuration.html#revocation-setup
+.. _Distribution: distribution.html
+.. _Badge Processor: processing.html#badge-processor