doc: update distribution backends section

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,93 @@
+@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 A (template)
+credly_admin -> credly : Creates a badge B (template)
+
+
+== Open edX Configuration ==
+
+oex_admin -> backend : Enters Credentials admin\n (Credly Badges app)
+oex_admin -> backend : Creates Organization configuration\n  (Credly client API connection)
+
+
+== Badges management ==
+
+oex_admin -> backend : Performs list action "Update badges from templates"
+backend -> credly : Requests available badge templates\n (Credly organization)
+backend <-- credly : Returns available (Org) badge templates
+
+rnote over badges,backend
+    - CredlyBadge(A) is created
+    - CredlyBadge(B) is created
+endrnote
+
+backend <-[#red]-> credly : Uses webhook to keep\n badge templates in sync?
+
+
+== Requirements setup ==
+
+oex_admin -> backend : Performs list action "Configure badges for course completion"
+
+rnote over badges,backend
+    - Award effect Requirements are created (selected badges)
+    - Revoke effect Requirements are created (selected badges)
+endrnote
+
+hnote over badges,backend #orange
+    At this moment all CredlyBadges
+    are configured to be given/revoked
+    for "ANY course completion"
+endhnote
+
+oex_admin -> backend : Specifies badge requirements
+
+rnote over badges,backend
+    Each Requirement must be set
+    with a specific course data
+    (course ID(s), etc.) to narrow down
+    award/revoke rule
+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 badges
+
+rnote over badges,backend
+    BadgeProcessor starts taking
+    into account new requirements.
+endhnote
+@enduml