doc: describe badges main concepts

docs/badges/_puml/badge-awarding-flow-sequence.puml

@@ -0,0 +1,63 @@
+@startuml name "Credly Badges award flow"
+
+!pragma teoz true
+autonumber
+
+title "Credly badges award effect (sequence diagram)"
+
+box "Open edX"
+    actor           "Open edX\n Learner" as learner
+    box "Platform IDA" #LightBlue
+        participant     "LMS" as lms
+    end box
+    participant     "EventBus" as ebus
+    box "Credentials IDA" #LightBlue
+        participant     "Badges app" as badges
+        participant     "Credly Badges app" as backend
+    end box
+end box
+box "External badging services"
+    box "Credly by Pearson" #LightSeaGreen
+        participant     "Credly" as credly
+    end box
+    participant     "Other" as other
+end box
+
+
+learner -> lms : Enters LMS course
+learner -> lms : Performs graded action\n (e.g. submits answer)
+
+lms -> ebus : Emits\n**COURSE_GRADE_NOW_PASSED**
+ebus <- badges : Receives\n**COURSE_GRADE_NOW_PASSED**
+
+rnote over badges,backend
+    **BadgeProcessor handles event**
+    - analyses Requirements
+    - updates Fulfillment(s)
+endrnote
+
+rnote over badges
+    **BadgeCollector handles event**
+    - analyses Fulfillment(s)
+    - awards Badge(s)
+    - emits awarding event
+endrnote
+
+ebus <- badges : Emits\n**BADGE_AWARDED**
+lms -> ebus : Receives\n**BADGE_AWARDED**
+
+rnote over backend
+    **CredlyBadgeCollector**
+    **handles event**
+    - analyses Fulfillment(s)
+    - awards CredlyBadge(s)
+    - emits awarding event
+endrnote
+
+ebus <- backend : Emits\n**BADGE_AWARDED**
+lms -> ebus : Receives\n**BADGE_AWARDED**
+
+backend -> credly : Issues user badge\n(API issuance request)
+backend -> learner : Optionally, notifies a Learner.
+
+@enduml

docs/badges/_puml/badge-revocation-flow-sequence.puml

@@ -0,0 +1,63 @@
+@startuml name "Credly Badges revoke flow"
+
+!pragma teoz true
+autonumber
+
+title "Credly badges revoke effect (sequence diagram)"
+
+box "Open edX"
+    actor           "Open edX\n Learner" as learner
+    box "Platform IDA" #LightBlue
+        participant     "LMS" as lms
+    end box
+    participant     "EventBus" as ebus
+    box "Credentials IDA" #LightBlue
+        participant     "Badges app" as badges
+        participant     "Credly Badges app" as backend
+    end box
+end box
+box "External badging services"
+    box "Credly by Pearson" #LightSeaGreen
+        participant     "Credly" as credly
+    end box
+    participant     "Other" as other
+end box
+
+
+learner -> lms : Enters LMS course
+learner -> lms : Performs graded action\n (e.g. submits answer)
+
+lms -> ebus : Emits\n**COURSE_GRADE_NOW_FAILED**
+ebus <- badges : Receives\n**COURSE_GRADE_NOW_FAILED**
+
+rnote over badges,backend
+    **BadgeProcessor handles event**
+    - analyses Requirements
+    - updates Fulfillment(s)
+endrnote
+
+rnote over badges
+    **BadgeCollector handles event**
+    - analyses Fulfillment(s)
+    - revokes Badge(s)
+    - emits revocation event
+endrnote
+
+ebus <- badges : Emits\n**BADGE_REVOKED**
+lms -> ebus : Receives\n**BADGE_REVOKED**
+
+rnote over backend
+    **CredlyBadgeCollector**
+    handles event:
+    - analyses Fulfillment(s)
+    - revokes Badge(s)
+    - emits revocation event
+endrnote
+
+ebus <- backend : Emits\n**BADGE_REVOKED**
+lms -> ebus : Receives\n**BADGE_REVOKED**
+
+backend -> credly : Revokes issued user badge\n(API revocation request)
+backend -> learner : Optionally, notifies a Learner.
+
+@enduml

docs/badges/_puml/credly-setup-sequence.puml

@@ -0,0 +1,78 @@
+@startuml name "Credly Badges setup"
+
+!pragma teoz true
+autonumber
+
+title "Credly badges intial configuration (sequence diagram)"
+
+box "Open edX"
+    actor           "Open edX\n Admin" as oex_admin
+    box "Platform IDA" #LightBlue
+        participant     "LMS" as lms
+    end box
+    participant     "EventBus" as ebus
+    box "Credentials IDA" #LightBlue
+        participant     "Badges app" as badges
+        participant     "Credly Badges app" as backend
+    end box
+end box
+box "External badging services"
+    box "Credly by Pearson" #LightSeaGreen
+        participant     "Credly" as credly
+        actor           "Credly\n Admin" as credly_admin
+    end box
+    participant     "Other" as other
+end box
+
+
+== Inital setup ==
+
+credly_admin -> credly : Configures API Client credentials\n for Open edX installation
+
+credly_admin -> credly : Creates Organization
+credly_admin -> credly : Creates a badge template "A"
+credly_admin -> credly : Creates a badge template "B"
+
+
+== Open edX Configuration ==
+
+oex_admin -> backend : Enters Credentials admin\n (Credly Badges app)
+oex_admin -> backend : Creates Organization configuration\n  (Credly client API connection)
+
+
+== Badge templates management ==
+
+oex_admin -> backend : Performs list action "Sync badge templates"
+backend -> credly : Requests available badge templates\n (Credly organization)
+backend <-- credly : Returns available (Org) badge templates
+
+rnote over badges,backend
+    - CredlyBadgeTemplate(A) is created
+    - CredlyBadgeTemplate(B) is created
+endrnote
+
+backend <-[#red]-> credly : Uses webhook to keep\n badge templates in sync?
+
+
+== Requirements setup ==
+
+oex_admin -> backend : Configures each template with forward and reverse effects.
+
+rnote over badges,backend
+    - Award effect Requirements are created
+    - Revoke effect Requirements are created
+endrnote
+
+hnote over badges,backend #LightGreen
+    At this moment all CredlyBadges
+    are configured to be given/revoked
+    for "specific course(s) completion".
+endhnote
+
+oex_admin -> backend : Activates configured badge templates
+
+rnote over badges,backend
+    BadgeProcessor starts taking
+    into account new requirements.
+endhnote
+@enduml

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 progress update made the related Requirement to be **fulfilled**.
+- Collector emits `BADGE_REQUIREMENT_FULFILLED` signal.
+- If so, Collector goes further and checks all related requirements (if any).
+- If all requirements for given badge template 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 new `UserCredential`_ record;
+- external event about a badge awarding fact is emitted;
+
+
+Badge revocation analysis
+-------------------------
+
+This is an alternative (reverse) pipeline step for requirements analysis with `revoke` effect set.
+
+- User's `Fulfillment`_ may be updated, so related Requirement stops being fulfilled.
+- Related badge template 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`;
+- external event about the badge revocation fact is emitted;
+
+.. _Badge Processor: details.html#badge-processor
+.. _Badge Collector: details.html#badge-collector
+.. _Fulfillment: details.html#fulfillment
+.. _UserCredential: details.html#usercredential