docs: add new Badges documentation

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 (`<credentials>/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

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");