diff --git a/docs/badges/index.rst b/docs/badges/index.rst index 7d7bdd1619..ecf5503f09 100644 --- a/docs/badges/index.rst +++ b/docs/badges/index.rst @@ -18,7 +18,7 @@ Current Badges version is highly integrated with the `Credly (by Pearson)`_ serv settings configuration examples - .. processing + processing .. collecting .. distribution .. details diff --git a/docs/badges/processing.rst b/docs/badges/processing.rst index 076c19d209..e4e4a577dc 100644 --- a/docs/badges/processing.rst +++ b/docs/badges/processing.rst @@ -1,39 +1,72 @@ Processing ========== -**Processing** is a process of: +Incoming events async processing happens in a separate event bus consumer process(es). +See the Event Bus documentation for details. -- Open edX `public signals` subscription -- badge template requirements analysis -- badge fulfillments update - -.. note:: - Events async processing happens in a separate specific (out of the standard Django request-response flow) worker process. - See EventBus documentation for details. Events subscription ------------------- -`Feature configuration`_ provides an exclusive list of processed events. -`Badge Processor`_ is auto-connected to listen to those event types. + Only explicitly configured `event types`_ take part in the processing. + +See Badges `default settings`_ for the default set of supported events. +Though, it is expected that any public signal from the `openedx-events`_ library can extend this set with a single requirement: its payload includes a learner PII (UserData object). + + +Learner identification +---------------------- + + Each incoming event must be associated with a specific learner. -All registered events are expected to carry user data. In addition, different event types include their specific data set which can be used for `badge requirements`_ specification. +The system tries to identify a learner by the `UserData` object in the event payload. +If the learner is not found, the event is ignored. + +The system also ensures that such learner exists in the Credentials (creates if needed). - External async events are retranslated as internal Credentials (standard Django) signals, so registered receivers can process it. Requirements analysis --------------------- -Once `Event` received, `Badge Processor`_ runs its processing pipeline. -As a result a relevant requirements set for a specific event type is formed. +Since any requirement is associated with a single event type, all relevant requirements are collected for the incoming signal: -Fulfillments update ---------------------- +- appropriate event type; +- active badge templates; + +Each requirement's rules are checked against the event payload. +Requirement processing is dropped as soon as the system recognizes not applying rules. + + +Progress update +--------------- + +Current learners' badge progress is stored in the ``Badge Progress`` record. + + Since badge templates can have more than one requirement, the system should track intermediate progresses as well. + +Once all rules of the processed requirement apply, the system: + +- ensures there is the badge progress record for the learner; +- marks the requirement as fulfilled for the learner; + +If a Badge Progress is recognized as completed (all requirements for the badge template are fulfilled), the system initiates the awarding process. + + +Badge awarding +-------------- + + Once all requirements for the badge template are fulfilled, the system should award the badge. + +On badge progress completion, the system: + +- creates an *internal* user credential record for the learner; +- notifies (public signal) about new badge awarded; +- tries to issue an *external* Credly badge for the learner; + +.. note:: -Once event-related requirements set is clear, Processor updates/creates corresponding `Fulfillments`_'s attributes for the event-learner. + The Badges application implements its extended ``UserCredential`` version (the CredlyBadge) to track external issuing state. Once the Credly badge is successfully issued the **CredlyBadge is updated with its UUID and state**. -.. _public events: https://github.com/openedx/openedx-events/blob/main/openedx_events/tooling.py -.. _Feature configuration: configuration.html#feature-configuration -.. _badge requirements: configuration.html#requirements-setup -.. _Badge Processor: details.html#badge-processor -.. _Fulfillments: details.html#fulfillment \ No newline at end of file +.. _event types: https://docs.openedx.org/projects/openedx-events/en/latest/ +.. _openedx-events: https://github.com/openedx/openedx-events +.. _default settings: settings.html#default-settings