From f9a84afd732f275ae77535932402e73473ff1a26 Mon Sep 17 00:00:00 2001 From: wowkalucky Date: Thu, 30 Nov 2023 17:51:03 +0200 Subject: [PATCH] doc: initiate Badges documentation --- docs/badges/_puml/badges-flow-sequence.puml | 58 ++++++++ .../_puml/credly-integration-sequence.puml | 58 ++++++++ docs/badges/collection.rst | 25 ++++ docs/badges/configuration.rst | 90 +++++++++++++ docs/badges/data.rst | 15 +++ docs/badges/details.rst | 124 ++++++++++++++++++ docs/badges/distribution.rst | 38 ++++++ docs/badges/feature_overview.rst | 70 ++++++++++ docs/badges/index.rst | 17 +++ docs/badges/overview.rst | 24 ++++ docs/badges/processing.rst | 33 +++++ docs/index.rst | 1 + 12 files changed, 553 insertions(+) create mode 100644 docs/badges/_puml/badges-flow-sequence.puml create mode 100644 docs/badges/_puml/credly-integration-sequence.puml create mode 100644 docs/badges/collection.rst create mode 100644 docs/badges/configuration.rst create mode 100644 docs/badges/data.rst create mode 100644 docs/badges/details.rst create mode 100644 docs/badges/distribution.rst create mode 100644 docs/badges/feature_overview.rst create mode 100644 docs/badges/index.rst create mode 100644 docs/badges/overview.rst create mode 100644 docs/badges/processing.rst diff --git a/docs/badges/_puml/badges-flow-sequence.puml b/docs/badges/_puml/badges-flow-sequence.puml new file mode 100644 index 0000000000..3ddd51a9d8 --- /dev/null +++ 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 \ncontext={user+course} +ebus -> credentials : Emits \ncontext={user+course} + + + +@enduml \ No newline at end of file diff --git a/docs/badges/_puml/credly-integration-sequence.puml b/docs/badges/_puml/credly-integration-sequence.puml new file mode 100644 index 0000000000..3ddd51a9d8 --- /dev/null +++ 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 \ncontext={user+course} +ebus -> credentials : Emits \ncontext={user+course} + + + +@enduml \ No newline at end of file diff --git a/docs/badges/collection.rst b/docs/badges/collection.rst new file mode 100644 index 0000000000..973fa0a493 --- /dev/null +++ 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 \ No newline at end of file diff --git a/docs/badges/configuration.rst b/docs/badges/configuration.rst new file mode 100644 index 0000000000..7d495736fb --- /dev/null +++ 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** **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 new file mode 100644 index 0000000000..42908101b1 --- /dev/null +++ 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 new file mode 100644 index 0000000000..2f5cf2bb84 --- /dev/null +++ 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 default=1 + - start optional + - end 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: + +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 + + + +.. image:: ../_static/images/badges-flow-sequence.png + :alt: Verifiable Credentials issuance sequence diagram + + +.. _Distribution backends: distribution.html \ No newline at end of file diff --git a/docs/badges/distribution.rst b/docs/badges/distribution.rst new file mode 100644 index 0000000000..a68bd722c4 --- /dev/null +++ b/docs/badges/distribution.rst @@ -0,0 +1,38 @@ +Distribution +============ + +System allows badges distribution to external services via pluggable backends. + +Each backend is responsible for: + +- communication between external service and Open edX (Credentials); +- implementation of service-specific badge types; +- its badges translation to native badges (mapping); +- earned badges projection to users' profiles; + +.. note:: + Currently, there is a single integration is implemented: + + - `Credly (by Pearson)`_ + +Credly +------ + +.. warning:: TBD + +Organizations +~~~~~~~~~~~~~ + + +Badge templates +~~~~~~~~~~~~~~~ + + +Badge acceptance +~~~~~~~~~~~~~~~~ + + +Badge management +~~~~~~~~~~~~~~~~ + +.. _Credly (by Pearson): https://info.credly.com/ \ No newline at end of file diff --git a/docs/badges/feature_overview.rst b/docs/badges/feature_overview.rst new file mode 100644 index 0000000000..49bf19deab --- /dev/null +++ b/docs/badges/feature_overview.rst @@ -0,0 +1,70 @@ +Badges overview +=============== + + + + +Badges configuration +-------------------- + + + +Events configuration +~~~~~~~~~~~~~~~~~~~~ + +An explicit list of system (public) events which are taken into account during badges processing. + +Badges creation +~~~~~~~~~~~~~~~~~~~ + +`Badge` objects are created via Credentials admin. +Badge must have unique identifier, name, icon?.. + +Requirements setup +~~~~~~~~~~~~~~~~~~ + +Each `Badge` must be associated with at least 1 system (public) event. + +- `Requirement` record defines `Badge <[rule]> Event` association +- `Requirement` record may define additional rules: + + - repetitive: 2 (event must happen twice to be `fulfilled`) + - timed: [, ] (event must happen in start-end period) + +`Badge` is `completed` for user once all attached `Requirements`` are `fulfilled`. + + +Badges processing +-------------------- + +Based on learners activity system (LMS) produces events with user context. + +`Credentials:badges` application listens to user-events (separate topic?). + +Once event received `badges:Collector`: + +- checks if there are Requirements for such event type: + - if no Requirements - drops processing +- updates `Fulfillment` records: + - `Collector` tries to pickup `Fulfillment` records for Event.user + - if no Fulfillments - drops processing + - checks Requirement restrictions (meta) + - updates each Fulfillments status +- on Fulfillment status change `Collector` also evaluates related Badge completion status +- if Badge completion detected (all Fulfillments was `fulfilled`): + - `Collector` emits new `BADGE_AWARDED` public event with `BadgeData` + - `UserCredential` record is created + +Now Badge(s) is earned for user. It is persistent within Open edX aka `origin` badge. + + +Badges distribution +-------------------- + +Open edX allows integrations with external badging platforms. + +In order to integrate with such service, a new backend must be developed. + +Distribution backends +~~~~~~~~~~~~~~~~~~~~~ + diff --git a/docs/badges/index.rst b/docs/badges/index.rst new file mode 100644 index 0000000000..020023817c --- /dev/null +++ b/docs/badges/index.rst @@ -0,0 +1,17 @@ +Badges +====== + +**Badges** are an another kind of **credentials**. + +---- + +.. toctree:: + :maxdepth: 1 + + overview + configuration + processing + collection + data + distribution + details diff --git a/docs/badges/overview.rst b/docs/badges/overview.rst new file mode 100644 index 0000000000..afccf05b99 --- /dev/null +++ b/docs/badges/overview.rst @@ -0,0 +1,24 @@ +Overview +======== + +Badges feature is described by the following items: + +- Learners *earn* badges based on Open edX platform activity. +- Learners' activity is expressed through `system events`_. +- System allows `badges management`_. +- Each badge must be configured with its `requirements`_. +- System `analyzes`_ user-specific events and controls badge requirements `fulfillment`_ by learners. +- On `badge completion`_ learners are awarded the badge. +- Earned badges are `collected`_ for learners within Credentials service. +- Credentials service may provide `relevant API endpoints`_ (badge configuration, earned badges, etc.) +- System allows `badges distribution`_ to external services via pluggable backends. + +.. _system events: configuration.html#events +.. _badges management: configuration.html#badges-management +.. _requirements: configuration.html#requirements-setup +.. _analyzes: processing.html +.. _fulfillment: processing.html +.. _badge completion: processing.html +.. _collected: collection.html +.. _relevant API endpoints: data.html +.. _badges distribution: distribution.html \ No newline at end of file diff --git a/docs/badges/processing.rst b/docs/badges/processing.rst new file mode 100644 index 0000000000..eac290f7ad --- /dev/null +++ b/docs/badges/processing.rst @@ -0,0 +1,33 @@ +Processing +========== + +**Processing** is a process of: + +- Open edX `public events` subscription +- badges requirements analysis +- badges fulfillments update + +Events subscription +------------------- + +Currently we are interested in a single Event Bus topic: + +- learning + +Badges application implements a subscription for learning-specific (LMS) events (with user context). + +Requirements analysis +--------------------- + +`EventProcessor`_ must ignore all events w/o learner context. +Once *user-learning* event received, EventProcessor looks through active badges requirements for this particular Event. + +If relevant requirements found EventProcessor: + +- checks Requirement meta for limitations (e.g. time range) +- updates corresponding `Fulfillments`_ for the event-learner (`times` counter) + + +.. _public events: https://github.com/openedx/openedx-events/blob/main/openedx_events/tooling.py +.. _EventProcessor: details.html#event-processor +.. _Fulfillments: details.html#fulfillment \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst index f1054682b9..86948d491a 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -28,4 +28,5 @@ This repository contains the edX Credentials Service, used as the backend to sup lms_user_id program_completion_emails decisions + badges/index