diff --git a/docs/badges/collecting.rst b/docs/badges/collecting.rst new file mode 100644 index 0000000000..3e0988e83a --- /dev/null +++ b/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 \ No newline at end of file diff --git a/docs/badges/collection.rst b/docs/badges/collection.rst deleted file mode 100644 index 973fa0a493..0000000000 --- a/docs/badges/collection.rst +++ /dev/null @@ -1,25 +0,0 @@ -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 index 7d495736fb..f69ad27ff0 100644 --- a/docs/badges/configuration.rst +++ b/docs/badges/configuration.rst @@ -3,8 +3,103 @@ 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 ----------------- @@ -12,12 +107,21 @@ 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 ~~~~~~~~ @@ -25,13 +129,25 @@ 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** **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 \ No newline at end of file diff --git a/docs/badges/data.rst b/docs/badges/data.rst deleted file mode 100644 index 42908101b1..0000000000 --- a/docs/badges/data.rst +++ /dev/null @@ -1,15 +0,0 @@ -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 index 2f5cf2bb84..0874615a28 100644 --- a/docs/badges/details.rst +++ b/docs/badges/details.rst @@ -3,7 +3,28 @@ Implementation Details Badges feature is implemented as a separate application within the Credentials Open edX service: - `credentials/apps/badges/` +.. code-block:: + + credentials/apps/badges/ + +Events (Event Bus) +------------------ + + Badges feature always relies on events (public signals) with user data. + +New events +~~~~~~~~~~ + +Badges feature extends the set of already `published events`_ with its own set of new public events: + +- `BADGE_AWARDED` (Credentials) +- `BADGE_REVOKED` (Credentials) + +In addition to already present `public events`_ Badges also rely on: + +- `COURSE_GRADE_NOW_PASSED` (LMS) +- `COURSE_GRADE_NOW_FAILED` (LMS) + Data models ----------- @@ -13,7 +34,7 @@ Badges application maintains a set of data models. Badge ~~~~~ -**Badge** data model extends `AbstractCredential`. It represents *native* credentials badges +**Badge** data model extends `AbstractCredential`. It represents *native* badges. (additionally see *distribution badges*). .. code-block:: python @@ -23,16 +44,18 @@ Badge Describes badge type. """ - uuid + - type: default="openedx" (native type) + - status: "inactive" | "active" | "archived" - name + - description - 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. +It carries *Rules*: **which** event, **how** and **when** must occur. Badge can have multiple Requirements. .. code-block:: python @@ -42,11 +65,11 @@ Badge can have multiple Requirements. Defines a single rule for badge type. """ - Badge (relation) - - event_type (association) - - meta (rules) - - times default=1 - - start optional - - end optional + - Event (relation) + - times default=1 (allows repetitive events) + - start optional (allows time range events) + - end optional (allows time range events) + - rule_set: default=1 (allows requirements combination) Fulfillment ~~~~~~~~~~~ @@ -60,9 +83,9 @@ Fulfillment Tracks rule fulfillment for user. """ - Requirement (relation) - - User (relation) - - completed: 0 | 1 + - username: - times: + - completed UserCredential ~~~~~~~~~~~~~~ @@ -73,52 +96,79 @@ Badges extend currently present: - program certificates - course certificates -Public events -------------- +.. code-block:: python -Since badges are always rely on user-specific events. + UserCredential: + """ + Earned Badge persistence. + """ + ... + - uuid + - username: + - status: "awarded" | "revoked" + ... -.. note:: - Possibly, we need a separate topic with user-events. - See: `EVENT_BUS_PRODUCER_CONFIG` -New events -~~~~~~~~~~ +Badge Processor +--------------- -Badges feature relies on already present public events: +**BadgeProcessor** (BP) is an entity which is responsible for incoming public events processing. -- `COURSE_GRADE_NOW_PASSED` should be expressed as public signal (what is a definition for course completion?) -- TBD +- `BadgeProcessor` class is inherited from the `BaseProcessor` which provides expected interface. +- `BadgeProcessor` is auto-registered as a receiver for all configured event types. -Badges feature introduces new public events: +Event processing pipeline +~~~~~~~~~~~~~~~~~~~~~~~~~ -- `BADGE_AWARDED` event (public signal) -- `BADGE_REVOKED` event (public signal) +For received Event: -Event Processor ---------------- +- active badges set identification; +- relevant requirements identification; +- (not implemented) requirements restrictions checks (e.g. time range) +- requirements effect application - corresponding fulfillments update for the given user -**EventProcessor** (EP) is an entity which is responsible for incoming public events processing. + `Badge Processor` doesn't bother about user's badging progress, since it is the main responsibility of the `Badge Collector`. -EventProcessor is configurable. `Distribution backends`_ are able to override its implementation. +.. note:: + `Distribution backends`_ should be able to override processing implementation. Badge Collector --------------- -**BadgeCollector** (BC) is an entity which is responsible for tracking badges progress for learners and awarding already completed badges. +**BadgeCollector** (BC) is an entity which is responsible for users badging progress tracking, as well as for awarding of already completed badges. + +- `BadgeCollector` class is inherited from the `BaseCollector` which provides expected interface. +- `BadgeCollector` is registered as a receiver for Fulfillment records. + +Badge Collector is subscribed for `Fulfillment` records updates. + +Badge collecting pipeline +~~~~~~~~~~~~~~~~~~~~~~~~~ +For updated requirement Fulfillment: + +- `award` effect + - single requirement fulfillment evaluation (completion flag is set) + - related requirements fulfillment evaluation (completion flag is set) + - badge completion evaluation + - completed badge awarding (UserCredential is created) +- `revoke` effect + - single requirement fulfillment revocation (completion flag is reset) + - completed badge revocation (UserCredential status="revoked") Feature sequence diagrams ------------------------- -Interaction flow happens as follows. - TBD + + -.. image:: ../_static/images/badges-flow-sequence.png - :alt: Verifiable Credentials issuance sequence diagram +.. .. image:: ../_static/images/badges-flow-sequence.png +.. :alt: Verifiable Credentials issuance sequence diagram +.. _published events: /event_bus.html#events-published +.. _public events: /event_bus.html#events-consumed .. _Distribution backends: distribution.html \ No newline at end of file diff --git a/docs/badges/distribution.rst b/docs/badges/distribution.rst index a68bd722c4..8718600093 100644 --- a/docs/badges/distribution.rst +++ b/docs/badges/distribution.rst @@ -1,38 +1,189 @@ Distribution ============ -System allows badges distribution to external services via pluggable backends. + System allows badges distribution to external services via backends. -Each backend is responsible for: +Badge distribution backends are Credentials plugins (installable applications). + +Each backend may be 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; +- earned badges propagation to service's user profiles; +- users notification; +- etc. .. note:: - Currently, there is a single integration is implemented: + Currently, there is a single integration implemented: - `Credly (by Pearson)`_ -Credly ------- +---- -.. warning:: TBD +Credly backend +-------------- -Organizations -~~~~~~~~~~~~~ +Credly badge distribution backend is implemented as a baked-in plugin: +.. code-block:: -Badge templates -~~~~~~~~~~~~~~~ + credentials/apps/badges/backends/credly/ +Credly badges backend registers its own section in the Credentials admin interface. -Badge acceptance -~~~~~~~~~~~~~~~~ +Configuration +~~~~~~~~~~~~~ +``Credly badge backend`` allows API authorization configuration for ``Credly service`` communication. + +Credly service has a concept of `Organizations`. + + For now, integration happens on behalf of a single Credly organization. Badge management ~~~~~~~~~~~~~~~~ -.. _Credly (by Pearson): https://info.credly.com/ \ No newline at end of file +Badge types are defined in Credly as ``badge templates``. Credly service allows badge templates creation in a context of Organization. + +The backend provides extended data model for a badge: + +.. code-block:: + + CredlyBadge(Badge): + """ + Describes Credly badge template. + """ + - - - unified attrs - - - + + - uuid + - status: "inactive" | "active" | "archived" + - name: + - description: + - icon: + + - - - specific attrs - - - + + - type: "credly" + - template_id: + +Badges creation +############### + +Credly badges can be created manually, but more preferable way is to use bulk operations: + +- ``create_badges_from_templates`` management command +- ``create_badges_from_templates`` admin list view action + +Both options perform the same: + +1. Pull available badge templates from `Credly API`_: + +.. code-block:: + + GET /organizations//badge_templates + +2. Create ``CredlyBadge`` records for each available template. + +Requirements setup +~~~~~~~~~~~~~~~~~~ + +Created badges `must be configured`_. + +Desired Requirements are created for each badge manually. + +.. note:: + For convenience there is related semi-automation badge configuration: + + - ``configure_single_course_completion`` management command + - ``configure_single_course_completion`` admin list view action + + Both options create Requirement for single arbitrary course completion event. + Requirements specification (e.g. ``course_id``) must be set manually. + +CCX courses +########### + + **TBD:** define how we map list of CCX courses to a single badge == (course A completion OR course B completion). + +Awarded badges +~~~~~~~~~~~~~~ + +Already awarded badges are stored as `UserCredential`_ records. + +Credly backend manages its extended version of user credential: + +.. code-block:: + + CredlyUserBadge(UserCredential): + """ + Earned Badge. + """ + - - - unified attrs - - - + ... + - uuid + - username: + - status: "awarded" | "revoked" + ... + + - - - specific attrs - - - + + - issued_badge_id: + - issued_at: + - accept_badge_url: + + +Side Effects +~~~~~~~~~~~~ + +`Badge Collector`_ emits signals when: + +- a badge is `awarded`_ +- a badge is `revoked`_ + +There are events which may be used as triggers for distribution **side effects**: + +- on award: + - credentials.apps.badges.backends.credly.handlers.notify_user_awarding + - credentials.apps.badges.backends.credly.handlers.issue_badge +- on revoke: + - credentials.apps.badges.backends.credly.handlers.notify_user_revocation + - credentials.apps.badges.backends.credly.handlers.revoke_badge + +Badge issuance +############## + +Badge issuance side effect is performed via `issue a badge Credly API`_. +Required Fields: + +.. code-block:: + + recipient_email: + issued_to_first_name: + issued_to_last_name: + badge_template_id: + issued_at: + +Badge revocation +################ + +Badge revocation side effect is performed via `revoke a badge Credly API`_. + +Required data: ``badge_id`` + +.. code-block:: + + PUT /organizations//badges//revoke + { + "reason": "Check bounced", + "suppress_revoke_notification_email": false + } + +.. _Credly (by Pearson): https://info.credly.com/ +.. _Credly API : https://www.credly.com/docs/badge_templates +.. _must be configured : configuration.html#requirements-setup +.. _UserCredential : details.html#usercredential +.. _Badge Collector : details.html#badge-collector +.. _awarded : collecting.html#badge-awarding +.. _revoked : collecting.html#badge-revocation +.. _issue a badge Credly API : https://www.credly.com/docs/issued_badges#issue-a-badge +.. _revoke a badge Credly API : https://www.credly.com/docs/issued_badges#revoke-a-badge \ No newline at end of file diff --git a/docs/badges/feature_overview.rst b/docs/badges/feature_overview.rst deleted file mode 100644 index 49bf19deab..0000000000 --- a/docs/badges/feature_overview.rst +++ /dev/null @@ -1,70 +0,0 @@ -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 index 020023817c..be589cb777 100644 --- a/docs/badges/index.rst +++ b/docs/badges/index.rst @@ -1,17 +1,35 @@ -Badges -====== +Badges (DRAFT) +============== -**Badges** are an another kind of **credentials**. + **Badges** are an another kind of **credentials**. + + +Badges feature is briefly described by the following items: + +- 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. +- System allows `badges distribution`_ to external services via pluggable backends. ---- .. toctree:: :maxdepth: 1 - overview + quickstart configuration processing - collection - data + collecting distribution details + +.. _badges management: configuration.html#badges-management +.. _requirements: configuration.html#requirements-setup +.. _analyzes: processing.html +.. _fulfillment: processing.html +.. _badge completion: processing.html +.. _collected: collecting.html +.. _relevant API endpoints: data.html +.. _badges distribution: distribution.html \ No newline at end of file diff --git a/docs/badges/overview.rst b/docs/badges/overview.rst deleted file mode 100644 index afccf05b99..0000000000 --- a/docs/badges/overview.rst +++ /dev/null @@ -1,24 +0,0 @@ -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 index eac290f7ad..16d61ef061 100644 --- a/docs/badges/processing.rst +++ b/docs/badges/processing.rst @@ -3,31 +3,37 @@ Processing **Processing** is a process of: -- Open edX `public events` subscription -- badges requirements analysis -- badges fulfillments update +- Open edX `public signals` subscription +- badge requirements analysis +- badge fulfillments update + +.. note:: + Events async processing happens in a separate specific (out of the standard Django request-response flow) worker process. + See EventBus documentation for details. Events subscription ------------------- -Currently we are interested in a single Event Bus topic: +`Feature configuration`_ provides an exclusive list of processed events. +`Badge Processor`_ is auto-connected to listen to those event types. -- learning +All registered events are expected to carry user data. In addition, different event types include their specific data set which can be used for `badge requirements`_ specification. -Badges application implements a subscription for learning-specific (LMS) events (with user context). + External async events are retranslated as internal Credentials (standard Django) signals, so registered receivers can process it. 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: +Once `Event` received, `Badge Processor`_ runs its processing pipeline. +As a result a relevant requirements set for a specific event type is formed. -- checks Requirement meta for limitations (e.g. time range) -- updates corresponding `Fulfillments`_ for the event-learner (`times` counter) +Fulfillments update +--------------------- +Once event-related requirements set is clear, Processor updates/creates corresponding `Fulfillments`_'s attributes for the event-learner. .. _public events: https://github.com/openedx/openedx-events/blob/main/openedx_events/tooling.py -.. _EventProcessor: details.html#event-processor +.. _Feature configuration: configuration.html#feature-configuration +.. _badge requirements: configuration.html#requirements-setup +.. _Badge Processor: details.html#badge-processor .. _Fulfillments: details.html#fulfillment \ No newline at end of file diff --git a/docs/badges/quickstart.rst b/docs/badges/quickstart.rst new file mode 100644 index 0000000000..f3f6d73e47 --- /dev/null +++ b/docs/badges/quickstart.rst @@ -0,0 +1,77 @@ +Quick start +=========== + + Learners *earn* badges based on Open edX platform activity. + +1. Enable feature +----------------- + +Badges feature is optional and it is disabled by default. +So, it must be enabled to be accessible. + +.. code-block:: + + # Credentials service: + ENABLE_BADGES = true + +2. Validate configuration +------------------------- + +Learners' activity is expressed through `system events`_. +Credentials Badges has an explicit `configuration`_ for: + +- **consumed events** - these events are a basis for **badging rules**; +- **produced events** - these events inform other services about **badging progress**; + +Possibly, one will want to extend incoming event types. + +3. Create your badges +--------------------- + +Badge have its `life-cycle`_ which starts from a `creation`_. +Newly created badges are inactive, since they are not configured. + +.. note:: + Badge `distribution backends`_ may extend standard badges management capabilities. + +4. Setup badge requirements +--------------------------- + +The most important part of badge configuration is `requirements specification`_. In short, at least one requirement must be associated with the Badge. + + Requirements describe what must be done before one can get the badge. + +Badge requirements control how badge completion is fulfilled (see currently `available use cases`_) + +Additionally, requirement can be configured with `revocation effect`_. + +5. Activate configured badge +---------------------------- + +Once badge requirements are configured, to make badge available for users one have to "enable" it - put in active state. + +Active badges start being taking into account by the `Badge Processor`_. + +6. Badges maintenance +-------------------- + +Badge can be "paused" by putting it in `inactive` state. Inactive state allows badge editing. + +7. Badges withdrawal +-------------------- + +Badge can be retired by putting it in `archived` state. Such badges are not processed anymore. + +--- + + + +.. _system events: details.html#events-event-bus +.. _configuration: configuration.html#feature-configuration +.. _life-cycle: configuration.html#badges-management +.. _creation: configuration.html#creation +.. _requirements specification: configuration.html#requirements-setup +.. _available use cases: configuration.html#use-cases +.. _revocation effect: configuration.html#revocation-setup +.. _Badge Processor: processing.html#badge-processor +.. _distribution backends: distribution.html \ No newline at end of file