From 0d78029bcc3ad9d450a82ba1ba2f8b2b39055e34 Mon Sep 17 00:00:00 2001
From: wowkalucky <wowkalucky@gmail.com>
Date: Mon, 8 Jan 2024 13:57:53 +0200
Subject: [PATCH] feat: add CredlyOrganization model description

---
 docs/badges/distribution.rst | 76 ++++++++++++++++++++++++++----------
 1 file changed, 55 insertions(+), 21 deletions(-)

diff --git a/docs/badges/distribution.rst b/docs/badges/distribution.rst
index c3b8d8fd09..3a8c8f3c2a 100644
--- a/docs/badges/distribution.rst
+++ b/docs/badges/distribution.rst
@@ -55,11 +55,27 @@ This application extends the core badges functions in the following ways:
 Configuration
 ~~~~~~~~~~~~~
 
-Credly badges extension allows API authorization configuration for ``Credly service`` communication.
+Credly badges extension allows `Credly web service API`_ authorization configuration.
 
-Credly service has a concept of `Organizations`.
+Organizations
+#############
 
-    Integration happens on behalf of a single Credly organization.
+.. note::
+    Credly service has a concept of `Organizations`.
+    Integration happens on behalf of a single Credly organization to Open edX installation.
+
+Credly Badges application allows creation of Credly organization records via admin interface.
+``CredlyOrganization`` record holds API credentials for a specific Credly organization:
+
+.. code-block:: python
+
+        CredlyOrganization(TimeStampedModel):
+            """
+            A single Credly organization.
+            """
+            - uuid: <ORGANIZATION-ID>
+            - name: <ORGANIZATION-NAME>
+            - api_key: <API-KEY>
 
 Badge templates management
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -69,23 +85,24 @@ This backend provides its own badge templates type:
 .. code-block::
 
     CredlyBadgeTemplate(BadgeTemplate):
-    """
-    Extended version of the core BadgeTemplate data model implementation.
+        """
+        Extended version of the core BadgeTemplate data model implementation.
 
-    In addition to standard field set also includes extra attributes from Credly badge template.
-    """
-    - - - unified attrs - - -
+        In addition to standard field set also includes extra attributes from Credly badge template.
+        """
+        - - - unified attrs - - -
 
-    - uuid
-    - status: "inactive" | "active" | "archived"
-    - name: <template-name>
-    - description: <template-description>
-    - icon: <template-image_url>
+        - organization: <CredlyOrganization (relation)>
+        - uuid
+        - name: <template-name>
+        - description: <template-description>
+        - icon: <template-image_url>
+        - status: "inactive" | "active" | "archived"
 
-    - - - specific attrs - - -
+        - - - specific attrs - - -
 
-    - type: "credly"
-    - template_id: <uuid>
+        - type: "credly"
+        - template_id: <uuid>
 
 Under the hood ``CredlyBadge`` data is split onto 2 data tables:
 
@@ -95,14 +112,15 @@ Under the hood ``CredlyBadge`` data is split onto 2 data tables:
 Badge templates creation
 ########################
 
-Credly badge templates can be created manually, but more preferable way is to use bulk operations:
+Credly badge templates can be created manually, but more preferable way is to use bulk operations.
+From ``CredlyOrganization`` list:
 
-- ``sync_badge_templates`` management command
-- ``sync_badge_templates`` admin list view action
+- ``sync_organization_badge_templates`` admin list view action
+- ``sync_organization_badge_templates`` management command
 
 Both options perform the same:
 
-1. Pull available badge templates from `Credly API`_:
+1. Pull available for Organization badge templates from `Credly API`_:
 
 .. code-block::
 
@@ -110,6 +128,21 @@ Both options perform the same:
 
 2. Create ``CredlyBadgeTemplate`` records for each available template.
 
+Badge templates synchronization
+###############################
+
+After the initial Credly badge templates creation on Open edX Credentials side, system starts listen to their updates via available web hooks:
+
+- ``badge_template.created`` (event is triggered whenever a badge template is created)
+    - system creates new ``CredlyBadgeTemplate`` in inactive state;
+    - badges are not start being processed until manual activation;
+- ``badge_template.changed`` (event is triggered whenever a badge template is changed)
+    - system updates corresponding ``CredlyBadgeTemplate`` relevant attributes;
+    - badges processing continues;
+- ``badge_template.deleted`` (event is triggered whenever a badge template is delete)
+    - system archives corresponding ``CredlyBadgeTemplate``;
+    - badges processing stops;
+
 Requirements setup
 ~~~~~~~~~~~~~~~~~~
 
@@ -274,4 +307,5 @@ Revocation flow mirrors awarding flow.
 .. _Requirements setup: distribution.html#requirements-setup
 .. _Awarded badges: distribution.html#awarded-badges
 .. _Side effects: distribution.html#side-effects
-.. _More details: distribution.html#more-details
\ No newline at end of file
+.. _More details: distribution.html#more-details
+.. _Credly web service API: https://www.credly.com/docs/web_service_api
\ No newline at end of file