diff --git a/docs/_static/images/badges/badges-admin-credly-templates-list.png b/docs/_static/images/badges/badges-admin-credly-templates-list.png new file mode 100644 index 000000000..2cfbe04f1 Binary files /dev/null and b/docs/_static/images/badges/badges-admin-credly-templates-list.png differ diff --git a/docs/_static/images/badges/badges-admin-credly-templates-sync.png b/docs/_static/images/badges/badges-admin-credly-templates-sync.png new file mode 100644 index 000000000..a7d2eea74 Binary files /dev/null and b/docs/_static/images/badges/badges-admin-credly-templates-sync.png differ diff --git a/docs/_static/images/badges/badges-admin-data-rules.png b/docs/_static/images/badges/badges-admin-data-rules.png new file mode 100644 index 000000000..60832012f Binary files /dev/null and b/docs/_static/images/badges/badges-admin-data-rules.png differ diff --git a/docs/_static/images/badges/badges-admin-progress-records.png b/docs/_static/images/badges/badges-admin-progress-records.png new file mode 100644 index 000000000..31754994f Binary files /dev/null and b/docs/_static/images/badges/badges-admin-progress-records.png differ diff --git a/docs/_static/images/badges/badges-admin-requirement-rules.png b/docs/_static/images/badges/badges-admin-requirement-rules.png new file mode 100644 index 000000000..524283031 Binary files /dev/null and b/docs/_static/images/badges/badges-admin-requirement-rules.png differ diff --git a/docs/_static/images/badges/badges-admin-rules-group.png b/docs/_static/images/badges/badges-admin-rules-group.png new file mode 100644 index 000000000..c48ba0059 Binary files /dev/null and b/docs/_static/images/badges/badges-admin-rules-group.png differ diff --git a/docs/_static/images/badges/badges-admin-template-details.png b/docs/_static/images/badges/badges-admin-template-details.png new file mode 100644 index 000000000..ff222b48d Binary files /dev/null and b/docs/_static/images/badges/badges-admin-template-details.png differ diff --git a/docs/_static/images/badges/badges-admin-template-requirements.png b/docs/_static/images/badges/badges-admin-template-requirements.png new file mode 100644 index 000000000..3d734f0f9 Binary files /dev/null and b/docs/_static/images/badges/badges-admin-template-requirements.png differ diff --git a/docs/_static/images/badges/badges-admin.png b/docs/_static/images/badges/badges-admin.png new file mode 100644 index 000000000..e05d8e9c5 Binary files /dev/null and b/docs/_static/images/badges/badges-admin.png differ diff --git a/docs/badges/configuration.rst b/docs/badges/configuration.rst new file mode 100644 index 000000000..cff25cd5a --- /dev/null +++ b/docs/badges/configuration.rst @@ -0,0 +1,153 @@ +Configuration +============= + +The Badges feature is configured via the Credentials admin interface. + +.. image:: ../_static/images/badges/badges-admin.png + :alt: Badges administration + +Credly Organizations +-------------------- + + Multiple Credly Organizations can be configured. + +**All communication between Open edX Credentials and Credly service happens on behalf of a Credly Organization.** + +Enter "Credly Organizations" list page (`/admin/badges/credlyorganization/`) and create a new item: + +- to set the UUID use your Credly Organization identifier; +- to set the authorization token issue one in the Credly Organization's dashboard; + +Check: the system pulls the Organization's details and updates its name. + +In case of errors check used credentials for the Organization. + +Badge templates +--------------- + + **Badge template** is another **credential** type. Credly badge template is a kind of a badge template. + +*Credly badge templates* (badge templates for brevity) are created in the Credly Organization's dashboard and then, if published, they are retrieved by the Credentials via API. + +Synchronization +~~~~~~~~~~~~~~~ + +To synchronize Credly badge templates for the Organization one should: + +- navigate "Credly badge templates" list page; +- select the Organization; +- use ``Sync organization badge templates`` action; + +.. image:: ../_static/images/badges/badges-admin-credly-templates-sync.png + :alt: Credly badge templates synchronization + +On success, the system will update the list of Credly badge templates for the Organization: + +- only badge templates with ``active`` state are pulled; +- Credly badge template records are created inactive (disabled); + +.. image:: ../_static/images/badges/badges-admin-credly-templates-list.png + :alt: Credly badge templates list + +For the usage a badge template must be configured and activated first. + +Badge Requirements +------------------ + + Requirements describe **what** and **how** must happen on the system to earn a badge. + +Badge Requirement(s) specification is a crucial part of badge template configuration. +At least one badge requirement must be associated with a badge template. + +Badge Requirements are listed inline on a badge template detail page. + +.. image:: ../_static/images/badges/badges-admin-template-requirements.png + :alt: Credly badge template requirements + +A badge template can can have multiple requirements. All badge requirements must be *fulfilled* to earn a badge. + +Event type +~~~~~~~~~~ + + Describes **what is expected to happen**. + +Available event type subset is pre-configured in the application settings. + +.. note:: + + Technically, any public signal from the `openedx-events`_ library can be used for badge template requirements setup, if it includes user PII (UserData), so users can be identified. + +Rules +~~~~~ + +A list of configured data rules (if any), see "Data Rules". + +Description +~~~~~~~~~~~ + +**Description** is an optional human-readable reminder that describes what the requirement is about. + + Badge Requirement can be **deeper specified** via its Data Rules. + +Group +~~~~~ + +Optional field for badge requirement. + +Allows mark 2 or more badge requirements as a group. Requirements group is fulfilled if any of its requirements is fulfilled ("OR" logic is applied inside a group). + +.. image:: ../_static/images/badges/badges-admin-rules-group.png + :alt: Badge requirement rules group + +See `configuration examples`_. + +Data Rules +---------- + + Describes **how it is expected to happen** + +Data Rules detail their parent Badge Requirement based on the expected event payload. + +To edit/update a Data Rule: + +- navigate to the Badge Requirement detail page (use ``Change`` inline link); +- find the "Data Rules" section and add a new item; + +.. image:: ../_static/images/badges/badges-admin-requirement-rules.png + :alt: Badge requirement rules edit + +**Each data rule describes a single expected payload value:** + +All key paths are generated based on the event type specified for the parent Badge Requirement. + +.. image:: ../_static/images/badges/badges-admin-data-rules.png + :alt: Badge requirement data rules + +1. **Key path** - payload path to the target attribute; +2. **Operator** - how to compare expected and actual values; +3. **Expected value** - an expected value for the target attribute; + +Please, see `configuration examples`_ for clarity. + +Activation +---------- + +Configured badge template can be activated: + +- navigate to the badge template detail page; +- check ``Is active`` checkbox; + + Activated badge template starts "working" immediately. + +.. image:: ../_static/images/badges/badges-admin-template-details.png + :alt: Badge template data structure + +Credly badge template record includes: + +1. Core credential attributes; +2. Badge template credential attributes; +3. Credly service attributes (state, dashboard link); +4. Configured requirements; + +.. _`configuration examples`: examples.html +.. _openedx-events: https://github.com/openedx/openedx-events \ No newline at end of file diff --git a/docs/badges/examples.rst b/docs/badges/examples.rst new file mode 100644 index 000000000..eaac8aea7 --- /dev/null +++ b/docs/badges/examples.rst @@ -0,0 +1,236 @@ +Configuration examples +====================== + +These examples will put some light on how to configure requirements and data rules for desired use cases. + +.. note:: + + **Any of the following examples can be combined together for more specific use cases**. + + +Implemented use cases +---------------------- + +ANY COURSE GRADE update +~~~~~~~~~~~~~~~~~~~~~~~ + + Not that useful. Any interaction with gradable block in any course leads to a badge. + +- Requirement 1: + - event type: ``org.openedx.learning.course.passing.status.updated.v1`` + - description: ``On any grade update.`` + +ANY COURSE completion +~~~~~~~~~~~~~~~~~~~~~ + + Requires **passing grade** for any course. + +- Requirement 1: + - event type: ``org.openedx.learning.course.passing.status.updated.v1`` + - description: ``On any course completion.`` +- Data rule 1: + - key path: ``status`` + - operator: ``equals`` + - value: ``passing`` + +ANY CCX course completion +~~~~~~~~~~~~~~~~~~~~~~~~~ + + Requires **passing grade** for any CCX course. + +- Requirement 1: + - event type: ``org.openedx.learning.ccx.course.passing.status.updated.v1`` + - description: ``On any CCX course completion.`` +- Data rule 1: + - key path: ``status`` + - operator: ``equals`` + - value: ``passing`` + +ANY COURSE completion EXCEPT a specific course +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + Requires **passing grade** for any course excluding the "Demo" course. + +- Requirement 1: + - event type: ``org.openedx.learning.course.passing.status.updated.v1`` + - description: ``On any course completion, but not the "Demo" course.`` +- Data rule 1: + - key path: ``status`` + - operator: ``equals`` + - value: ``passing`` +- Data rule 2: + - key path: ``course.course_key`` + - operator: ``not equals`` + - value: ``course-v1:edX+DemoX+Demo_Course`` + +SPECIFIC COURSE completion +~~~~~~~~~~~~~~~~~~~~~~~~~~ + + Requires **passing grade** for exact course ("Demo" course). + +- Requirement 1: + - event type: ``org.openedx.learning.course.passing.status.updated.v1`` + - description: ``On the Demo course completion.`` +- Data rule 1: + - key path: ``status`` + - operator: ``equals`` + - value: ``passing`` +- Data rule 2: + - key path: ``course.course_key`` + - operator: ``equals`` + - value: ``course-v1:edX+DemoX+Demo_Course`` + +MULTIPLE SPECIFIC COURSES completion +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + All specified courses must be completed. + +- Requirement 1: + - event type: ``org.openedx.learning.course.passing.status.updated.v1`` + - description: ``On the "Demo" course AND "Other" course completion.`` +- Data rule 1: + - key path: ``status`` + - operator: ``equals`` + - value: ``passing`` +- Data rule 2: + - key path: ``course.course_key`` + - operator: ``equals`` + - value: ``course-v1:edX+DemoX+Demo_Course`` +- Data rule 3: + - key path: ``course.course_key`` + - operator: ``equals`` + - value: ``course-v1:edX+DemoX+OTHER_Course`` + +SPECIFIC CCX course completion +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + Requires **passing grade** for exact CCX course ("Demo CCX1" course). + +- Requirement 1: + - event type: ``org.openedx.learning.ccx.course.passing.status.updated.v1`` + - description: ``On the Demo CCX1 course completion.`` +- Data rule 1: + - key path: ``status`` + - operator: ``equals`` + - value: ``passing`` +- Data rule 2: + - key path: ``course.ccx_course_key`` + - operator: ``equals`` + - value: ``ccx-v1:edX+DemoX+Demo_Course+ccx@1`` + +ANY CCX course completion ON a SPECIFIC MASTER course +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + Requires **passing grade** for any "child" CCX course that based on the master "Demo" course. + +- Requirement 1: + - event type: ``org.openedx.learning.ccx.course.passing.status.updated.v1`` + - description: ``On any Demo CCX course completion.`` +- Data rule 1: + - key path: ``status`` + - operator: ``equals`` + - value: ``passing`` +- Data rule 2: + - key path: ``course.master_course_key`` + - operator: ``equals`` + - value: ``course-v1:edX+DemoX+Demo_Course`` + +ANY CCX course completion ON a SPECIFIC MASTER course EXCEPT a SPECIFIC CCX course +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + Complicated. Requires **passing grade** for any "child" CCX course that based on the master "Demo" course, excluding the "Demo CCX2" course. + +- Requirement 1: + - event type: ``org.openedx.learning.ccx.course.passing.status.updated.v1`` + - description: ``On any Demo CCX course completion.`` +- Data rule 1: + - key path: ``status`` + - operator: ``equals`` + - value: ``passing`` +- Data rule 2: + - key path: ``course.master_course_key`` + - operator: ``equals`` + - value: ``course-v1:edX+DemoX+Demo_Course`` +- Data rule 3: + - key path: ``course.ccx_course_key`` + - operator: ``not equals`` + - value: ``ccx-v1:edX+DemoX+Demo_Course+ccx@2`` + +ONE OF MULTIPLE SPECIFIC COURSES completion +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + A single from specified courses must be completed. Grouped rules are processed as "ANY FROM A GROUP". + +- Requirement 1: + - event type: ``org.openedx.learning.course.passing.status.updated.v1`` + - description: ``On the "Demo" course OR "Other" course completion.`` + - group: ``unique-group-identifier`` +- Data rule 1: + - key path: ``status`` + - operator: ``equals`` + - value: ``passing`` +- Data rule 2: + - key path: ``course.course_key`` + - operator: ``equals`` + - value: ``course-v1:edX+DemoX+Demo_Course`` + +- Requirement 2: + - event type: ``org.openedx.learning.course.passing.status.updated.v1`` + - description: ``On the "Demo" course OR "Other" course completion.`` + - group: ``unique-group-identifier`` +- Data rule 1: + - key path: ``status`` + - operator: ``equals`` + - value: ``passing`` +- Data rule 2: + - key path: ``course.course_key`` + - operator: ``equals`` + - value: ``course-v1:edX+DemoX+OTHER_Course`` + + +SPECIFIC MASTER course OR ANY of its CCX courses EXCEPT a SPECIFIC CCX course completion +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + Here **group = demo** is used to group rules 2 and 3, so any of them lead to a badge. + +- Requirement 1: + - event type: ``org.openedx.learning.ccx.course.passing.status.updated.v1`` + - description: ``On the "Demo" course completion OR...`` + - group: ``demo`` +- Data rule 1: + - key path: ``status`` + - operator: ``equals`` + - value: ``passing`` +- Data rule 2: + - key path: ``course.course_key`` + - operator: ``equals`` + - value: ``course-v1:edX+DemoX+Demo_Course`` + +- Requirement 2: + - event type: ``org.openedx.learning.ccx.course.passing.status.updated.v1`` + - description: ``...On any Demo CCX courses completion EXCLUDING CCX3.`` + - group: ``demo`` +- Data rule 1: + - key path: ``status`` + - operator: ``equals`` + - value: ``passing`` +- Data rule 3: + - key path: ``course.master_course_key`` + - operator: ``equals`` + - value: ``course-v1:edX+DemoX+Demo_Course`` +- Data rule 4: + - key path: ``course.ccx_course_key`` + - operator: ``not equals`` + - value: ``ccx-v1:edX+DemoX+Demo_Course+ccx@3`` + +----- + +Future work +----------- + +- Events set extension (e.g. "Email activation", "Profile data completion", "Course section completion", ...); +- Repetitive events (e.g. "5 arbitrary courses completion"); +- Prerequisite events (e.g. "5 specific courses completion in a specified order"); +- Time-ranged event (e.g. "Arbitrary course completion during the February 2022"); +- Badge dependencies (e.g. "Badge A + Badge B = Badge C"); +- Multiple times same badge earning (e.g. "3 arbitrary course completions make badge earned x3"); diff --git a/docs/badges/index.rst b/docs/badges/index.rst new file mode 100644 index 000000000..bb44eb81b --- /dev/null +++ b/docs/badges/index.rst @@ -0,0 +1,26 @@ +Badges +====== + + The Badges feature allows learners to earn achievements (badges) for their learning activities. + +- **Badge Template** is another kind of **credential**. +- **Badge** is another kind of **user credential**. + + +Current Badges version is highly integrated with the `Credly (by Pearson)`_ service, but it is fully prepared to be used separately. + +---- + +.. toctree:: + :maxdepth: 1 + + quickstart + settings + configuration + examples + processing + .. collecting + .. distribution + .. details + +.. _Credly (by Pearson): https://info.credly.com/ \ No newline at end of file diff --git a/docs/badges/processing.rst b/docs/badges/processing.rst new file mode 100644 index 000000000..44ec4785f --- /dev/null +++ b/docs/badges/processing.rst @@ -0,0 +1,75 @@ +Processing +========== + +Incoming events async processing happens in a separate event bus consumer process(es). +See the Event Bus documentation for details. + + +Events subscription +------------------- + + Only explicitly configured `event types`_ take part in the processing. + +See Badges `default settings`_ for the default set of supported events. +Though, it is expected that any public signal from the `openedx-events`_ library can extend this set with a single requirement: its payload includes a learner PII (UserData object). + + +Learner identification +---------------------- + + Each incoming event must be associated with a specific learner. + +The system tries to identify a learner by the `UserData` object in the event payload. +If the learner is not found, the event is ignored. + +The system also ensures that such learner exists in the Credentials (creates if needed). + + +Requirements analysis +--------------------- + +Since any requirement is associated with a single event type, all relevant requirements are collected for the incoming signal: + +- appropriate event type; +- active badge templates; + +Each requirement's rules are checked against the event payload. +Requirement processing is dropped as soon as the system recognizes not applying rules. + + +Progress update +--------------- + +Current learners' badge progress is stored in the ``Badge Progress`` record. + + Since badge templates can have more than one requirement, the system should track intermediate progresses as well. + +Once all rules of the processed requirement apply, the system: + +- ensures there is the badge progress record for the learner; +- marks the requirement as fulfilled for the learner; + +.. image:: ../_static/images/badges/badges-admin-progress-records.png + :alt: Badge progress records + +If a Badge Progress is recognized as completed (all requirements for the badge template are fulfilled), the system initiates the awarding process. + + +Badge awarding +-------------- + + Once all requirements for the badge template are fulfilled, the system should award the badge. + +On badge progress completion, the system: + +- creates an *internal* user credential record for the learner; +- notifies (public signal) about new badge awarded; +- tries to issue an *external* Credly badge for the learner; + +.. note:: + + The Badges application implements its extended ``UserCredential`` version (the CredlyBadge) to track external issuing state. Once the Credly badge is successfully issued the **CredlyBadge is updated with its UUID and state**. + +.. _event types: https://docs.openedx.org/projects/openedx-events/en/latest/ +.. _openedx-events: https://github.com/openedx/openedx-events +.. _default settings: settings.html#default-settings diff --git a/docs/badges/quickstart.rst b/docs/badges/quickstart.rst new file mode 100644 index 000000000..f9ec2f39f --- /dev/null +++ b/docs/badges/quickstart.rst @@ -0,0 +1,141 @@ +Quick Start +=========== + + Learners *earn* badges based on Open edX platform activity. + + +0. Credly service prerequisites +------------------------------- + +Since current Badges version is deeply integrated with the Credly service, Credly account is a prerequisite. + +- a **Credly Organization** is expected to be created; +- 1 or more **badge templates** are expected to be created and activated in the Organization; +- Credly Organization **authorization token** is issued; + +1. Enable feature +----------------- + +Badges feature is optional and it is disabled by default. +So, it must be enabled to be accessible. + +.. code-block:: + + # LMS service: + FEATURES["BADGES_ENABLED"] = True + + # Credentials service: + BADGES_ENABLED = True + +2. Configure Credly integration +------------------------------- + + Multiple Credly Organizations can be configured. + +Enter the Credentials service admin interface and configure the integration with the Credly service: + +- create a Credly Organization (`/admin/badges/credlyorganization/`); +- set the UUID for the Organization; +- set the authorization token; + +Check: the system pulls the Organization data and updates its name. + + +3. Synchronize badge templates +------------------------------ + +From the "Credly Organizations" list, select the Organization(s) you want to use and select ``Sync organization badge templates`` action. + +The system pulls the list of badge templates from the Credly Organization. Navigate to the "Credly badge templates" list and check newly created templates. + +4. Setup badge requirements +--------------------------- + + Requirements describe **what** and **how** must happen on the system to earn a badge. + +The crucial part of the badge template configuration is requirements specification. +At least one requirement must be associated with a badge template. + +Enter the first badge template details page and configure its requirement(s): + +- find "Badge Requirements" section; +- add new item and select an event type (what is expected to happen); +- optionally, put a description; +- save and navigate to the Requirement details (``Change`` link); + +- optionally, specify a data rule(s) in the "Data Rules" section (how exactly it is expected to happen); +- add new item and describe the rule; +- select a key path - target payload parameter; +- select an operator - how to compare the value; +- enter a value - expected parameter's value; + +.. note:: + + A configuration for the badge template that must be issued on a **specific course completion** looks as following: + + - Requirement: + - event type: ``org.openedx.learning.course.passing.status.updated.v1`` + - description: ``On the Demo course completion.`` + - Data rule 1: + - key path: ``course.course_key`` + - operator: ``equals`` + - value: ``course-v1:edX+DemoX+Demo_Course`` + - Data rule 2: + - key path: ``status`` + - operator: ``equals`` + - value: ``passing`` + +It is possible to put more than one requirement in a badge template. + +5. Activate configured badge templates +-------------------------------------- + + To active a badge template check the ``is active`` checkbox on its edit page. + +Once badge requirements are configured, it should be "enabled" to start "working". + +Active badge templates start being taking into account immediately. + +.. warning:: + + Configuration updates for active badge template are discouraged since it may cause learners' inconsistent experience. + +6. See users Badge Progress +--------------------------- + +Current badge progress can be seen in the "Badge progress records" section. + +Since badge template can have more than one requirement, there can be partially completed badges. + +7. See awarded user credentials +------------------------------- + +Already earned badges are listed in the "Credly badges" list page. + + The Credly Badge is an extended version of a user credential record. + +Once badge progress is complete (all requirements were *fulfilled*), the system: + +- creates internal user credential (CredlyBadge); +- notifies about the badge awarding (public signal); +- requests Credly service to issue the badge (API request). + +8. See issued Credly badges +--------------------------- + +Earned internal badges (user credentials) propagate to the Credly service. + +On a successful Credly badge issuing the CredlyBadge user credential is updated with its requisites: + +- external UUID; +- external state; + +The Credly badge is visible in the Credly service. + + +9. Badge template withdrawal +---------------------------- + +Badge template can be deactivated by putting it in the inactive state (``is active`` checkbox). + +Inactive badge templates are ignored during the processing. diff --git a/docs/badges/settings.rst b/docs/badges/settings.rst new file mode 100644 index 000000000..4e3e5e9d0 --- /dev/null +++ b/docs/badges/settings.rst @@ -0,0 +1,171 @@ +Settings +======== + +Badges feature settings allow configuration: + +- feature availability; +- event bus public signals subset for badges; +- the Credly service integration details (URLs, sandbox usage, etc.); + + +Feature switch +-------------- + +The Badges feature is under a feature switch (disabled by default). + +To enable the feature, update these settings as follows: + +.. code-block:: python + + # Platform services settings: + FEATURES["BADGES_ENABLED"] = True + + # Credentials service settings: + BADGES_ENABLED = True + + +Default settings +---------------- + +The feature has its configuration: + +.. code-block:: python + + # Credentials settings: + BADGES_CONFIG = { + # these events become available in requirements/penalties setup: + "events": [ + "org.openedx.learning.course.passing.status.updated.v1", + "org.openedx.learning.ccx.course.passing.status.updated.v1", + ], + # Credly integration: + "credly": { + "CREDLY_BASE_URL": "https://credly.com/", + "CREDLY_API_BASE_URL": "https://api.credly.com/v1/", + "CREDLY_SANDBOX_BASE_URL": "https://sandbox.credly.com/", + "CREDLY_SANDBOX_API_BASE_URL": "https://sandbox-api.credly.com/v1/", + "USE_SANDBOX": False, + }, + # Requirements data rules: + "EXCLUDED_KEY_PATHS": [ + "user.id", + "user.is_active", + "user.pii.username", + "user.pii.email", + "user.pii.name", + ], + } + +- ``events`` - explicit event bus signals list (only events with PII user data in payload are applicable). +- ``credly`` - Credly integration details. +- ``EXCLUDED_KEY_PATHS`` - event payload paths to exclude from data rule options (see: Configuration_). + +Credly integration +~~~~~~~~~~~~~~~~~~ + +- USE_SANDBOX - enables Credly sandbox usage (development, testing); +- CREDLY_BASE_URL - Credly service host URL; +- CREDLY_API_BASE_URL - Credly API host URL; +- CREDLY_SANDBOX_BASE_URL - Credly sandbox host URL; +- CREDLY_SANDBOX_API_BASE_URL - Credly sandbox API host URL; + + +Event bus settings +------------------ + + ``learning-badges-lifecycle`` is the event bus topic for all Badges related events. + +The Badges feature has updated event bus producer configurations for the Platform and the Credentials services. + +Source public signals +~~~~~~~~~~~~~~~~~~~~~ + +Platform's event bus producer configuration was extended with 2 public signals: + +- information about the fact someone's course grade was updated (allows course completion recognition); +- information about the fact someone's CCX course grade was updated (allows CCX course completion recognition); + +.. code-block:: python + + # Platform services settings: + EVENT_BUS_PRODUCER_CONFIG = { + ... + + "org.openedx.learning.course.passing.status.updated.v1": { + "learning-badges-lifecycle": { + "event_key_field": "course_passing_status.course.course_key", + "enabled": _should_send_learning_badge_events, + }, + }, + "org.openedx.learning.ccx.course.passing.status.updated.v1": { + "learning-badges-lifecycle": { + "event_key_field": "course_passing_status.course.course_key", + "enabled": _should_send_learning_badge_events, + }, + }, + } + +Emitted public signals +~~~~~~~~~~~~~~~~~~~~~~ + +The Badges feature introduced 2 own event types: + +- information about the fact someone has earned a badge; +- information about the fact someone's badge was revoked; + +.. code-block:: python + + # Credentials service settings: + EVENT_BUS_PRODUCER_CONFIG = { + ... + + "org.openedx.learning.badge.awarded.v1": { + "learning-badges-lifecycle": {"event_key_field": "badge.uuid", "enabled": True }, + }, + "org.openedx.learning.badge.revoked.v1": { + "learning-badges-lifecycle": {"event_key_field": "badge.uuid", "enabled": True }, + }, + } + +Consuming workers +~~~~~~~~~~~~~~~~~ + + Consumers implementation depends on the used event bus. + +Event bus options: + +- Redis Streams +- Kafka +- ... + +The Credentials and the Platform services **produce** (push) their public signals as messages to the stream. + +To **consume** (pull) those messages a consumer process is required. + +Redis Streams +############# + +When the Redis Streams event bus is used, the ``-learning-badges-lifecycle`` stream is used for messages transport. + +For producing and consuming a single package (broker) is used - event-bus-redis_. + +"Event Bus Redis" is implemented as a Django application and provides a Django management command for consuming messages +(see all details in the package's README). + +.. code-block:: bash + + # Credentials service consumer example: + /edx/app/credentials/credentials/manage.py consume_events -t learning-badges-lifecycle -g credentials_dev --extra={"consumer_name":"credentials_dev.consumer1"} + + # LMS service consumer example: + /edx/app/edxapp/edx-platform/manage.py lms consume_events -t learning-badges-lifecycle -g lms_dev --extra={"consumer_name":"lms_dev.consumer1"} + +.. note:: + + **Credentials event bus consumer** is crucial for the Badges feature, since it is responsible for all incoming events processing. + + **LMS event bus consumer** is only required if LMS wants to receive information about badges processing results (awarding/revocation). + + +.. _Configuration: configuration.html +.. _event-bus-redis: https://github.com/openedx/event-bus-redis \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst index 482dbc571..d4adbfd38 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -25,3 +25,4 @@ This repository contains the edX Credentials Service, used as the backend to sup edx_extensions lms_user_id decisions + badges/index