docs: add grouped requirements examples

docs/badges/configuration.rst

@@ -77,13 +77,30 @@ Available event type subset is pre-configured in the application settings.
 
     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
 ----------
 
@@ -132,5 +149,5 @@ Credly badge template record includes:
 3. Credly service attributes (state, dashboard link);
 4. Configured requirements;
 
-.. _openedx-events: https://github.com/openedx/openedx-events
-.. _`configuration examples`: examples.html
+.. _`configuration examples`: examples.html
+.. _openedx-events: https://github.com/openedx/openedx-events

docs/badges/examples.rst

@@ -7,14 +7,24 @@ These examples will put some light on how to configure requirements and data rul
 
     **Any of the following examples can be combined together for more specific use cases**.
 
-    e.g.: "Course A and Course B completion."
 
 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.``
@@ -26,6 +36,8 @@ ANY COURSE completion
 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.``
@@ -37,9 +49,11 @@ ANY CCX course completion
 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.``
+    - description: ``On any course completion, but not the "Demo" course.``
 - Data rule 1:
     - key path: ``status``
     - operator: ``equals``
@@ -52,6 +66,8 @@ ANY COURSE completion EXCEPT a specific 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.``
@@ -67,9 +83,11 @@ SPECIFIC COURSE completion
 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 completion.``
+    - description: ``On the "Demo" course AND "Other" course completion.``
 - Data rule 1:
     - key path: ``status``
     - operator: ``equals``
@@ -86,6 +104,8 @@ MULTIPLE SPECIFIC COURSES completion
 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.``
@@ -101,6 +121,8 @@ SPECIFIC CCX course completion
 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.``
@@ -116,6 +138,8 @@ ANY CCX course completion ON a SPECIFIC MASTER 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.``
@@ -130,18 +154,65 @@ ANY CCX course completion ON a SPECIFIC MASTER course EXCEPT a SPECIFIC CCX cour
 - Data rule 3:
     - key path: ``course.ccx_course_key``
     - operator: ``not equals``
-    - value: ``ccx-v1:edX+DemoX+Demo_Course+ccx@1``
+    - 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.``
+- 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``
+    - group: ``any logical unique identifier``
+- Data rule 3:
+    - key path: ``course.course_key``
+    - operator: ``equals``
+    - value: ``course-v1:edX+DemoX+OTHER_Course``
+    - group: ``any logical unique identifier``
 
+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 OR any Demo CCX courses completion BUT NOT CCX3.``
+- 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``
+    - group: ``demo``
+- Data rule 3:
+    - key path: ``course.master_course_key``
+    - operator: ``equals``
+    - value: ``course-v1:edX+DemoX+Demo_Course``
+    - group: ``demo``
+- Data rule 4:
+    - key path: ``course.ccx_course_key``
+    - operator: ``not equals``
+    - value: ``ccx-v1:edX+DemoX+Demo_Course+ccx@3``
 
 -----
 
 Future work
 -----------
 
-- Event combination alternatives... (e.g. "Logical `OR` rule sets: Course A OR Course B completion");
-
-- Single generic event (e.g. "Email activation", "Profile data completion");
-- Repetitive events (e.g. "5 arbitrary course completion");
+- 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");