-
Notifications
You must be signed in to change notification settings - Fork 0
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
[WIP] feat: [ACI-240] Badges documentation #48
base: aci.main
Are you sure you want to change the base?
Conversation
docs/badges/configuration.rst
Outdated
.. code-block:: sh | ||
|
||
# credentials settings: | ||
BADGES_CONFIG = { |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
To discuss: do we have any cases for configuring this in the runtime (e.g., through admin panel) using this configuration from settings as fallback?
docs/badges/collecting.rst
Outdated
On `BADGE_REQUIREMENTS_COMPLETE` signal: | ||
|
||
- awarding handler creates `UserCredential`_ record; | ||
- emits external event about the badge awarding fact; |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
- emits external event about the badge awarding fact; | |
- emits external event `org.openedx.learning.badge.awarded.v1`; |
docs/badges/collecting.rst
Outdated
Configured `Badge Collector`_ is auto-subscribed for any updates in `Fulfillment`_ records. | ||
|
||
|
||
Badge completion analysis |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Badge completion analysis | |
Badge completion processing |
docs/badges/collecting.rst
Outdated
- emits external event about the badge awarding fact; | ||
|
||
|
||
Badge revocation analysis |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Badge revocation analysis | |
Badge revocation processing |
docs/badges/configuration.rst
Outdated
Badges management | ||
----------------- | ||
|
||
Badges management includes the following life-cycle stages or maintenance activities: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I believe it will be good to add here state diagram for displaying lifecycle, something like this may be modified, and used in the documentation
docs/badges/details.rst
Outdated
- `COURSE_GRADE_NOW_FAILED` (LMS) | ||
|
||
|
||
Data models |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Please check this ERD, it's better to have a visual representation of the data model
https://dbdiagram.io/d/Open-edX-Credly-Badges-645cd5efdca9fb07c4e805a4
ERD for the Credentials service can be found there - https://lucid.app/lucidchart/ac49c90e-9718-4f37-9135-f3c0c9a62017/edit?invitationId=inv_8f93357e-0a72-440f-a91a-19f94e78d2a5&page=pt-o3H4-vyK.#
docs/badges/distribution.rst
Outdated
|
||
Each backend may be responsible for: | ||
|
||
- communication between external service and Open edX (Credentials); |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
- communication between external service and Open edX (Credentials); | |
- communication between external badge issuing service and Open edX (Credentials); |
I find it a little confusing to read 'badge' being used in some places to refer to the badge template, and in others to refer to the issued badge. Could we more clearly define these as 'badge template' and either 'badge' or 'issued badge'? I think most backends make this distinction: Credly - badge template and badge; Badgr - badge class and assertion. |
docs/badges/configuration.rst
Outdated
|
||
BADGES_CONFIG["events"]["outgoing"]["topics"] = ["badges"] | ||
|
||
By default these event types are dynamically auto-registered to EventBus producer in addition to already present in `EVENT_BUS_PRODUCER_CONFIG`. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This is very convenient but I could see it also being surprising when trying to debug and understand where events are coming from. Walking into credentials from other apps, you would not expect other config to be auto-registering events. The flip-side of having to do this manually is not great either as that could lead to a different set of errors during setup. Not a blocker but I wish there was a better way for this to be explicit without making setup more error prone.
At the very least when we add the relevant code, we should make sure to add comments near where the event bus defaults are configured to so that operators know that some events come from the BADGES_CONFIG as well.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yeah... I still doubt it. I don't like implicit events extension either.
Technically, there are no required events for the feature - we can simplify everything:
- no implicit auto-registration for badges-specific events in favor of manual explicit event-bus producer registration for new badge-events;
- there will be incoming event types filter only;
I'll update the draft later. Everything should become more transparent then.
docs/badges/details.rst
Outdated
Badges feature extends the set of already `published events`_ with its own set of new public events: | ||
|
||
- `BADGE_AWARDED` (Credentials) | ||
- `BADGE_REVOKED` (Credentials) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Have the new events been proposed or accepted yet?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
These two are planned as a part of the openedx/openedx-events#303.
WIP.
on: | ||
push: | ||
branches: [aci.documentation] |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Will this eventually be carried over to the Credentials project for the master
branch? Or is this just temporary for this feature branch/fork?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Nope. It's temporary, just for internal convenience.
docs/badges/collecting.rst
Outdated
|
||
On `BADGE_REQUIREMENTS_NOT_COMPLETE` signal: | ||
|
||
- revocation handler updates `UserCredential`_ record's status to `revoked`; |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Will badges have proprietary statuses? Are they using the same awarded
and revoked
statuses that course and program credentials issued use?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The Badge
credential type is planned as the UserCredential
descendant (so, internal statuses will be consistent). There will be a special extended type specific for Credly though, but it will live in the Credly "backend" plugin.
Generally, we want to split "core", simple, self-contained badges functionality, and Credly-specific extensions.
docs/badges/collecting.rst
Outdated
|
||
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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
What would cause us to reconsider fulfillment requirements? Would this be caused by a failing grade? Are there any other actions that would be cause for us to reconsider revocation of the badge?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The Requirement
entity is aimed to implement a unified approach for future more complex badge rules. Currently, it will be a pretty straightforward usage - a single event leads to the badge earning/revocation.
docs/badges/configuration.rst
Outdated
- uuid (unique identifier, auto-generated) | ||
- name (verbose label - currently, out of localization) | ||
- icon(image) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Should status
be part of these properties -- inactive
, active
, and archived
?
docs/badges/configuration.rst
Outdated
Revocation setup (reverse effect) | ||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
|
||
During badge template configuration additional decision must be made: wether badges of the given type are `revocable` if required conditions are not the case anymore. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
nit: wether
--> whether
docs/badges/details.rst
Outdated
Requirement | ||
~~~~~~~~~~~ | ||
|
||
**Requirement** describes an association between a BadgeTemplate and an Event. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Event
can be an overloaded term -- is the Event
referenced here separate from the event bus and the Open edX events?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yeah, needs a more specific term here. This will be clarified.
docs/badges/distribution.rst
Outdated
Overview | ||
~~~~~~~~ | ||
|
||
Credly badges distribution backend is implemented as a baked-in plugin. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
When I read plugin, I think "external requirement/library optionally installed". Just confirming, this is not that -- this functionality will be part of the base Credentials service, but is totally optional if the Open edX Operator wants to take advantage of it.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Also -- is the Credly
functionality optional from the rest of the Badges implementation? Or will it require the Operator to have a Credly account for any Badge functionality?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
On one hand, we want Credly extra functions to be optional, but still a part of the standard codebase (disabled by default, but available if needed out of the box). Currently, it is designed as a separate installable credentials application (which is prepared to be extracted into a separate repo, but is baked-in within its parental badges
app and pre-added to requirements).
This is a matter of discussion.
The idea behind such "complexity":
- to provide a live example of an extension for the
badges
app; - to have the ability to extract (if needed in the future) from the main repo;
- design badges extensions with respect to the core Badges configuration (this is in progress);
docs/badges/distribution.rst
Outdated
""" | ||
- uuid: <ORGANIZATION-ID> | ||
- name: <ORGANIZATION-NAME> | ||
- api_key: <API-KEY> |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'm not familiar with Credly and thus know nothing about how they manage their API keys and the permissions/actions they allow.
How secure does this API key need to be? Is this something that will be configured (and thus visible) in Django Admin? Or will they need to be more secure (and managed/treated like a secret)?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It is just how Credly's API dev documentation requires. Nothing special from us here.
We agreed with the stakeholders that we treat credential service admins as reliable/responsible persons (at least at this point).
docs/badges/distribution.rst
Outdated
- on award: | ||
- credentials.apps.badges.distribution.credly.handlers.notify_user_awarding | ||
- credentials.apps.badges.distribution.credly.handlers.issue_badge | ||
- on revoke: | ||
- credentials.apps.badges.distribution.credly.handlers.notify_user_revocation | ||
- credentials.apps.badges.distribution.credly.handlers.revoke_badge |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
There are times when partners of ours don't want to message learners' when credentials are awarded, mostly because the system is designed in a way to award Credentials when they earn a passing grade (and likely haven't truly finished the course).
Will these notifications be optional?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
User notifications are still being discussed.
In this docs, it is mostly a hook for a discussion. An option to think about.
We update the docs based on decisions made.
docs/badges/distribution.rst
Outdated
|
||
recipient_email: <user-email> | ||
issued_to_first_name: <str> | ||
issued_to_last_name: <str> |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Names are hard, should we be looking at the full_name
fields versus First/Last? Or is this a requirement on the Credly side?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
docs/badges/distribution.rst
Outdated
PUT /organizations/<organization_id>/badges/<badge_id>/revoke | ||
{ | ||
"reason": "Check bounced", | ||
"suppress_revoke_notification_email": false |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Maybe this answers my above question about optionally notifying learners about a badge being awarded?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yes, user notification is a topic for the final requirements.
docs/badges/processing.rst
Outdated
|
||
.. note:: | ||
Events async processing happens in a separate specific (out of the standard Django request-response flow) worker process. | ||
See EventBus documentation for details. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Do you think it's worth linking to Event Bus documentation? https://openedx.atlassian.net/wiki/spaces/AC/pages/3127869624/Event+Bus+Project
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think so.
There is still a dedicated section within this documentation itself.
docs/badges/processing.rst
Outdated
|
||
Once event-related requirements set is clear, Processor updates/creates corresponding `Fulfillments`_'s attributes for the event-learner. | ||
|
||
.. _public events: https://github.com/openedx/openedx-events/blob/main/openedx_events/tooling.py |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Is this supposed to be linked to somewhere? Or is there a mismatch between the public signals
placeholder and the public events
link defined here?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We'll revise the consistency of terminology through these docs. Yeah, it's crucial not to produce misconception here.
docs/badges/quickstart.rst
Outdated
Quick Start | ||
=========== | ||
|
||
Learners *earn* badges based on Open edX platform activity. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Should we expand this with a sentence-or-two about what a badge is? Might be useful for people that dive right into the Quick Start
docs.
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** |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'm a little confused by this part. Are we potentially going to be emitting the BADGE_AWARDED
event twice? Or are these separate event types -- one tied to native badges and another for Credly badges?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks, it seems that this piece requires optimization/clarification. Noted.
8afa23d
to
3aa6219
Compare
d7ee9c3
to
7609686
Compare
See compiled live the Badges documentation updates for convenience.