From f18a7920eb854bfff0fa14b5255737a06e45e610 Mon Sep 17 00:00:00 2001 From: Glib Glugovskiy Date: Sun, 8 Mar 2026 23:57:58 +0100 Subject: [PATCH 1/3] docs: update readme and fix typos in credentials sharing docs --- README.rst | 37 ++++++++++++++----- docs/badges/configuration/accredible.rst | 4 +- docs/badges/configuration/credly.rst | 4 +- docs/badges/index.rst | 2 +- docs/badges/processing.rst | 10 ++--- docs/badges/quickstart.rst | 2 +- docs/badges/settings.rst | 2 +- docs/verifiable_credentials/components.rst | 4 +- docs/verifiable_credentials/configuration.rst | 2 +- docs/verifiable_credentials/extensibility.rst | 6 +-- docs/verifiable_credentials/overview.rst | 2 +- docs/verifiable_credentials/quickstart.rst | 2 +- docs/verifiable_credentials/storages.rst | 4 +- 13 files changed, 50 insertions(+), 31 deletions(-) diff --git a/README.rst b/README.rst index 0eadf6910..ebab83314 100644 --- a/README.rst +++ b/README.rst @@ -1,20 +1,38 @@ -edX Credentials Service |Codecov|_ -==================================== +============================ +Open edX Credentials Service +============================ -.. |Codecov| image:: http://codecov.io/github/edx/credentials/coverage.svg?branch=master -.. _Codecov: http://codecov.io/github/edx/credentials?branch=master +| |status-badge| |license-badge| |CI| |Codecov| -This repository contains the edX Credentials Service, which supports course and program certificates. This service is a -replacement for the ``certificates`` app in ``edx-platform``. +.. |CI| image:: https://github.com/openedx/credentials/actions/workflows/ci.yml/badge.svg + :target: https://github.com/openedx/credentials/actions?query=workflow%3ACI + :alt: Test suite status -Credentials can be run as part of devstack_ or Tutor_ (using the tutor_credentials_ plugin). +.. |Codecov| image:: https://codecov.io/github/openedx/credentials/coverage.svg?branch=master + :target: https://codecov.io/github/openedx/credentials?branch=master + :alt: Code coverage -.. _devstack: https://github.com/openedx/devstack +.. |status-badge| image:: https://img.shields.io/badge/Status-Maintained-brightgreen + :alt: Maintained + +.. |license-badge| image:: https://img.shields.io/github/license/openedx/credentials.svg + :target: https://github.com/openedx/credentials/blob/master/LICENSE + :alt: License + +Purpose +======= + +This repository contains the Open edX Credentials Service, which supports course and program certificates. +This service is an extension to `openedx-platform`_ providing a set of unique features in the credentials domain such as Badges, Verifiable Credentials, Learning Records, and Program Certificates. + +The easiest way to run Credentials service is by using Tutor_, the community-supported, Docker-based Open edX distribution, by installing the tutor_credentials_ plugin. + +.. _openedx-platform: https://github.com/openedx/openedx-platform/tree/master .. _tutor: https://docs.tutor.edly.io/ .. _tutor_credentials: https://github.com/overhangio/tutor-credentials Where to run `make` commands --------------------------- +---------------------------- Due to the nature of developing in containers, some commands must be ran inside the container. Currently most commands can be ran either inside the container or inside a local virtual environement, once developer requirements have been @@ -102,3 +120,4 @@ Our real-time conversations are on Slack_. .. _`discussion forums`: https://discuss.openedx.org .. _Slack: http://openedx.slack.com/ + diff --git a/docs/badges/configuration/accredible.rst b/docs/badges/configuration/accredible.rst index 3efbdbe62..0d2baeee7 100644 --- a/docs/badges/configuration/accredible.rst +++ b/docs/badges/configuration/accredible.rst @@ -15,7 +15,7 @@ Accredible API Configurations Multiple Accredible API Configurations can be configured. -**All communication between Open edX Credentials and Accredible service happens on behalf of a Accredible API config.** +**All communication between Open edX Credentials and Accredible service happens on behalf of an Accredible API config.** Go to the Accredible API Configs section in the admin panel and create a new item: @@ -160,7 +160,7 @@ Configured group can be activated: - navigate to the group detail page; - check ``Is active`` checkbox; - Activated groups starts "working" immediately. + Activated groups start "working" immediately. Accredible group record includes: diff --git a/docs/badges/configuration/credly.rst b/docs/badges/configuration/credly.rst index 15aaeb82f..a34880d93 100644 --- a/docs/badges/configuration/credly.rst +++ b/docs/badges/configuration/credly.rst @@ -36,9 +36,9 @@ Webhooks .. note:: - Webhooks is a connection with Credly and external platform that allows your server to be notified about events occuring within Credly. + Webhooks is a connection with Credly and external platform that allows your server to be notified about events occurring within Credly. -Webhooks are set up on Credly management dashboard as Credly is a main initiator of the syncronization. +Webhooks are set up on Credly management dashboard as Credly is a main initiator of the synchronization. You should be able to select an action from the list so that whenever the specified action occurs internally, the external system is alerted. diff --git a/docs/badges/index.rst b/docs/badges/index.rst index 0885241d6..167cdbac1 100644 --- a/docs/badges/index.rst +++ b/docs/badges/index.rst @@ -11,7 +11,7 @@ Current Badges version is highly integrated with the `Credly (by Pearson)`_ and What is Credly? --------------- -**Credly** is a end-to-end solution for creating, issuing, and managing digital Credentials. Organizations use **Credly** to recognize their learners' achievements. +**Credly** is an end-to-end solution for creating, issuing, and managing digital Credentials. Organizations use **Credly** to recognize their learners' achievements. Learners can store badges in their Credly profile to visualize their professional success - which courses were completed and when. Badges provide employers and peers concrete evidence of what learners have diff --git a/docs/badges/processing.rst b/docs/badges/processing.rst index e80dce16c..e4887275f 100644 --- a/docs/badges/processing.rst +++ b/docs/badges/processing.rst @@ -38,7 +38,7 @@ Since any requirement is associated with a single event type, all relevant requi 2. 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. +Requirement processing is skipped as soon as any rule doesn't match. Progress update @@ -72,7 +72,7 @@ On badge progress completion, the system: 1. creates an *internal* user credential record for the learner; 2. notifies (public signal) about new badge awarded; -3. tries to issue an *external* Credly badge for the learner; +3. tries to issue an *external* badge for the learner; .. note:: @@ -85,9 +85,9 @@ On badge progress completion, the system: Badge revocation ---------------- -Badges can also be revoked. Its a separete set of rules that need to be set up. +Badges can also be revoked. It's a separate set of rules that need to be set up. -1. Go to Badge Penalties section in admin panel (admin/badges/badge_pentalties). +1. Go to Badge Penalties section in admin panel (admin/badges/badge_penalties). .. image:: ../_static/images/badges/badges-admin-penalty-rules.png :alt: Badge penalties @@ -99,6 +99,6 @@ Badges can also be revoked. Its a separete set of rules that need to be set up. .. _Configuration: configuration.html -When a learner's badge is revoked by Credly, the Credentials IDA will be notified and will update it's internal records. The status of the badge will change from `awarded` to `revoked` upon successful revocation. +When a learner's badge is revoked by Credly, the Credentials IDA will be notified and will update its internal records. The status of the badge will change from `awarded` to `revoked` upon successful revocation. The badge cannot be reissued once it has been revoked. diff --git a/docs/badges/quickstart.rst b/docs/badges/quickstart.rst index 011acd0f2..c167de902 100644 --- a/docs/badges/quickstart.rst +++ b/docs/badges/quickstart.rst @@ -129,7 +129,7 @@ It is possible to put more than one requirement in a badge template. 5. Activate configured badge templates -------------------------------------- - To active a badge template check the ``is active`` checkbox on its edit page. + To activate a badge template check the ``is active`` checkbox on its edit page. Once badge requirements are set up, it should be “enabled” to start “working”. diff --git a/docs/badges/settings.rst b/docs/badges/settings.rst index 4168279c5..66515eb81 100644 --- a/docs/badges/settings.rst +++ b/docs/badges/settings.rst @@ -174,7 +174,7 @@ To **consume** (pull) those messages a consumer process is required. Redis Streams ############# -When the Redis Streams event bus is used, the ``-learning-badges-lifecycle`` stream is used for messages transport. +When the Redis Streams event bus is used, the ``-learning-badges-lifecycle`` stream is used for messages transport. For producing and consuming a single package (broker) is used - event-bus-redis_. diff --git a/docs/verifiable_credentials/components.rst b/docs/verifiable_credentials/components.rst index 0fe40e16d..4173ba036 100644 --- a/docs/verifiable_credentials/components.rst +++ b/docs/verifiable_credentials/components.rst @@ -50,7 +50,7 @@ Issuance Line Issuance line has its unique identifier and additionally includes this information: 1. **User Credential** - related Open edX achievement (e.g. "Program Certificate") -2. **Issuer ID** - issuer's which signs this verifiable credential +2. **Issuer ID** - issuer which signs this verifiable credential 3. **Storage ID** - a storage backend (digital wallet) which will keep a verifiable credential 4. **Processing status** - if a verifiable credential was successfully uploaded to storage 5. **Status list info** - indicates if a verifiable credential still valid and unique status index within an Issuer's status list @@ -74,7 +74,7 @@ The Verifiable Credentials feature extends the `Learner Record MFE`_ with additi Status List API --------------- -There are a plenty of reasons verifiable credential may be already invalid, inactive or disposed: +There are plenty of reasons verifiable credential may be already invalid, inactive or disposed: - revocation - implicit expiration diff --git a/docs/verifiable_credentials/configuration.rst b/docs/verifiable_credentials/configuration.rst index 7f2c615a5..1ca1dbb14 100644 --- a/docs/verifiable_credentials/configuration.rst +++ b/docs/verifiable_credentials/configuration.rst @@ -163,7 +163,7 @@ Issuer configuration helpers root@credentials:/edx/app/credentials/credentials# ./manage.py create_default_issuer -Initial Issuance configuration is created based on VERIFIABLE_CREDENTIALS[DEFAULT_ISSUER] via data migration during the first deployment. Helper allows manually repeat that is needed (Additional configurations can be created from django admin interface). +Initial Issuance configuration is created based on VERIFIABLE_CREDENTIALS[DEFAULT_ISSUER] via data migration during the first deployment. This helper allows repeating the process manually if needed (Additional configurations can be created from django admin interface). **Remove Issuance Configuration based on Issuer ID.** diff --git a/docs/verifiable_credentials/extensibility.rst b/docs/verifiable_credentials/extensibility.rst index 9c1c2dc96..e99e1a0c8 100644 --- a/docs/verifiable_credentials/extensibility.rst +++ b/docs/verifiable_credentials/extensibility.rst @@ -46,7 +46,7 @@ Both `data models`_ and `storages`_ may be implemented as Credentials IDA instal .. note:: - For storage plugin example, please, see the `openedx-wallet`_ training storage (by the `Raccoon Gang`_) . + For storage plugin example, please, see the `openedx-wallet`_ training storage (by the `Raccoon Gang`_). .. _Verifiable Credentials Data Model v1.1: https://www.w3.org/TR/vc-data-model-1.1/ .. _Open Badges Specification v3.0: https://1edtech.github.io/openbadges-specification/ob_v3p0.html @@ -59,6 +59,6 @@ Both `data models`_ and `storages`_ may be implemented as Credentials IDA instal .. _Learner Credential Wallet: https://lcw.app .. _DRF: https://www.django-rest-framework.org/ .. _Status List v2021: components.html#status-list-api -.. _VC1.1 model: https://github.com/openedx/credentials/tree/master/credentials/apps/verifiable_credentials/composition/verifiable_credentials.py -.. _OB3.0 model: https://github.com/openedx/credentials/tree/master/credentials/apps/verifiable_credentials/composition/open_badges.py +.. _VC1.1 model: https://github.com/openedx/credentials/blob/master/credentials/apps/verifiable_credentials/composition/verifiable_credentials.py +.. _OB3.0 model: https://github.com/openedx/credentials/blob/master/credentials/apps/verifiable_credentials/composition/open_badges.py .. _openedx-wallet: https://github.com/raccoongang/openedx-wallet \ No newline at end of file diff --git a/docs/verifiable_credentials/overview.rst b/docs/verifiable_credentials/overview.rst index b13182be8..d839b92f3 100644 --- a/docs/verifiable_credentials/overview.rst +++ b/docs/verifiable_credentials/overview.rst @@ -3,7 +3,7 @@ Verifiable Credentials An optional feature that allows issuance of the `Verifiable Credentials`_ based on the Open edX achievements. - *Verifiable credentials will allows us to represent our achievements in a provable, portable, sharable, privacy and autonomy preserving way.* + *Verifiable credentials will allow us to represent our achievements in a provable, portable, sharable, privacy and autonomy preserving way.* Please, see `Extensibility`_ section for the list of supported: diff --git a/docs/verifiable_credentials/quickstart.rst b/docs/verifiable_credentials/quickstart.rst index 0755e9e53..98dc90c74 100644 --- a/docs/verifiable_credentials/quickstart.rst +++ b/docs/verifiable_credentials/quickstart.rst @@ -43,7 +43,7 @@ See `Management commands`_ for more details. 3. Issuer credentials setup --------------------------- -Generated issuer credentials we'll use to update automatically generated with stub values Issuance Configuration. +Use the generated credentials to replace the stub values in the auto-created Issuance Configuration. Enter Credentials Administration interface and find "VERIFIABLE CREDENTIALS" section (`/admin/verifiable_credentials/issuanceconfiguration/`). diff --git a/docs/verifiable_credentials/storages.rst b/docs/verifiable_credentials/storages.rst index 83f202b5d..ff5039594 100644 --- a/docs/verifiable_credentials/storages.rst +++ b/docs/verifiable_credentials/storages.rst @@ -1,7 +1,7 @@ Storages ======== -Currently there is the only digital wallet is supported for production. +Currently only one digital wallet is supported for production. Learner Credential Wallet ------------------------- @@ -19,7 +19,7 @@ LCWallet maintainer (`Digital Credentials Consortium`_) requires verifiable cred .. note:: - For development/testing purposes a `Sandbox Registry`_ is available. If you would like to be added to the Sandbox Registry, please open a pull requests directly against that repository, matching the format for existing issuers in `registry.json` + For development/testing purposes a `Sandbox Registry`_ is available. If you would like to be added to the Sandbox Registry, please open a pull request directly against that repository, matching the format for existing issuers in `registry.json` Learner experience ~~~~~~~~~~~~~~~~~~ From 14c281f8f028042800b27f6b08edb907fc83149e Mon Sep 17 00:00:00 2001 From: Glib Glugovskiy Date: Tue, 10 Mar 2026 11:44:23 +0100 Subject: [PATCH 2/3] docs(vc): move credentials sharing docs under the same parent dir --- docs/index.rst | 11 ++++----- .../badges/configuration/accredible.rst | 14 +++++------ .../badges/configuration/credly.rst | 18 +++++++------- .../badges/configuration/index.rst | 0 docs/{ => sharing}/badges/examples.rst | 0 docs/{ => sharing}/badges/index.rst | 6 ++--- docs/{ => sharing}/badges/processing.rst | 4 ++-- docs/{ => sharing}/badges/quickstart.rst | 0 docs/{ => sharing}/badges/settings.rst | 0 docs/sharing/index.rst | 23 ++++++++++++++++++ ...ifiable_credentials-issuance-sequence.puml | 0 .../verifiable_credentials/components.rst | 8 +++---- .../verifiable_credentials/configuration.rst | 0 .../verifiable_credentials/extensibility.rst | 0 .../verifiable_credentials/overview.rst | 0 .../verifiable_credentials/quickstart.rst | 0 .../verifiable_credentials/storages.rst | 24 +++++++++---------- .../verifiable_credentials/tech_details.rst | 2 +- .../verifiable_credentials/usage.rst | 0 19 files changed, 66 insertions(+), 44 deletions(-) rename docs/{ => sharing}/badges/configuration/accredible.rst (91%) rename docs/{ => sharing}/badges/configuration/credly.rst (90%) rename docs/{ => sharing}/badges/configuration/index.rst (100%) rename docs/{ => sharing}/badges/examples.rst (100%) rename docs/{ => sharing}/badges/index.rst (98%) rename docs/{ => sharing}/badges/processing.rst (96%) rename docs/{ => sharing}/badges/quickstart.rst (100%) rename docs/{ => sharing}/badges/settings.rst (100%) create mode 100644 docs/sharing/index.rst rename docs/{ => sharing}/verifiable_credentials/_puml/verifiable_credentials-issuance-sequence.puml (100%) rename docs/{ => sharing}/verifiable_credentials/components.rst (96%) rename docs/{ => sharing}/verifiable_credentials/configuration.rst (100%) rename docs/{ => sharing}/verifiable_credentials/extensibility.rst (100%) rename docs/{ => sharing}/verifiable_credentials/overview.rst (100%) rename docs/{ => sharing}/verifiable_credentials/quickstart.rst (100%) rename docs/{ => sharing}/verifiable_credentials/storages.rst (86%) rename docs/{ => sharing}/verifiable_credentials/tech_details.rst (97%) rename docs/{ => sharing}/verifiable_credentials/usage.rst (100%) diff --git a/docs/index.rst b/docs/index.rst index 9f16300dc..58fd2865c 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -12,20 +12,19 @@ This repository contains the Open edX Credentials Service, used as the backend t overview getting_started - asset_pipeline - testing - internationalization - theming credentials_admin learner_records configuring_certificates - verifiable_credentials/overview + sharing/index + asset_pipeline + theming pathways analytics + testing + internationalization credentials_api event_bus edx_extensions lms_user_id program_completion_emails decisions - badges/index diff --git a/docs/badges/configuration/accredible.rst b/docs/sharing/badges/configuration/accredible.rst similarity index 91% rename from docs/badges/configuration/accredible.rst rename to docs/sharing/badges/configuration/accredible.rst index 0d2baeee7..e044bfb21 100644 --- a/docs/badges/configuration/accredible.rst +++ b/docs/sharing/badges/configuration/accredible.rst @@ -7,7 +7,7 @@ Accredible Configuration The Badges feature is configured in the Credentials admin panel. -.. image:: ../../_static/images/badges/badges-admin.png +.. image:: ../../../_static/images/badges/badges-admin.png :alt: Badges administration Accredible API Configurations @@ -38,7 +38,7 @@ To synchronize Accredible groups for the API Configuration one should: - select the API Config; - use ``Sync groups`` action; -.. image:: ../../_static/images/badges/badges-admin-groups-sync.png +.. image:: ../../../_static/images/badges/badges-admin-groups-sync.png :alt: Accredible groups synchronization On success, the system will update the list of Accredible groups: @@ -57,7 +57,7 @@ At least one badge requirement must be associated with a group. Badge Requirements are listed inline on a group detail page. -.. image:: ../../_static/images/badges/badges-admin-template-requirements.png +.. image:: ../../../_static/images/badges/badges-admin-template-requirements.png :alt: Credly badge template requirements A badge template can have multiple requirements. All badge requirements must be *fulfilled* before the system will issue a badge to a learner. @@ -95,7 +95,7 @@ Requirements group is fulfilled if any of its requirements is fulfilled. "OR" logic is applied inside a Group. -.. image:: ../../_static/images/badges/badges-admin-rules-group.png +.. image:: ../../../_static/images/badges/badges-admin-rules-group.png :alt: Badge requirement rules group See :ref:`Configuration examples for Badging`. @@ -112,14 +112,14 @@ To edit/update a Data Rule: - navigate to the Badge Requirement detail page (use ``Change`` inline link); - find the "Data Rules" section and add a new item; -.. image:: ../../_static/images/badges/badges-admin-requirement-rules.png +.. image:: ../../../_static/images/badges/badges-admin-requirement-rules.png :alt: Badge requirement rules edit **Each data rule describes a single expected payload value:** All key paths are generated based on the event type specified for the parent Badge Requirement. -.. image:: ../../_static/images/badges/badges-admin-data-rules.png +.. image:: ../../../_static/images/badges/badges-admin-data-rules.png :alt: Badge requirement data rules 1. **Key path** - payload path to the target attribute @@ -149,7 +149,7 @@ A penalty setup is similar to a badge requirement, but has different effect: it When all penalty rules have been applied, a learner's progress towards a badge is reset. -.. image:: ../../_static/images/badges/badges-admin-penalty-rules.png +.. image:: ../../../_static/images/badges/badges-admin-penalty-rules.png :alt: Badge penalty rules edit Activation diff --git a/docs/badges/configuration/credly.rst b/docs/sharing/badges/configuration/credly.rst similarity index 90% rename from docs/badges/configuration/credly.rst rename to docs/sharing/badges/configuration/credly.rst index a34880d93..33c6bb48e 100644 --- a/docs/badges/configuration/credly.rst +++ b/docs/sharing/badges/configuration/credly.rst @@ -7,7 +7,7 @@ Credly Configuration The Badges feature is configured in the Credentials admin panel. -.. image:: ../../_static/images/badges/badges-admin.png +.. image:: ../../../_static/images/badges/badges-admin.png :alt: Badges administration Credly Organizations @@ -53,7 +53,7 @@ To synchronize Credly badge templates for the Organization one should: - select the Organization; - use ``Sync organization badge templates`` action; -.. image:: ../../_static/images/badges/badges-admin-credly-templates-sync.png +.. image:: ../../../_static/images/badges/badges-admin-credly-templates-sync.png :alt: Credly badge templates synchronization On success, the system will update the list of Credly badge templates for the Organization: @@ -61,7 +61,7 @@ On success, the system will update the list of Credly badge templates for the Or - only badge templates with ``active`` state are pulled; - Credly badge template records are created inactive (disabled); -.. image:: ../../_static/images/badges/badges-admin-credly-templates-list.png +.. image:: ../../../_static/images/badges/badges-admin-credly-templates-list.png :alt: Credly badge templates list For a badge template to be considered during the processing it must be configured (to have at least 1 requirement) and activated (enabled) first. @@ -76,7 +76,7 @@ At least one badge requirement must be associated with a badge template. Badge Requirements are listed inline on a badge template detail page. -.. image:: ../../_static/images/badges/badges-admin-template-requirements.png +.. image:: ../../../_static/images/badges/badges-admin-template-requirements.png :alt: Credly badge template requirements A badge template can have multiple requirements. All badge requirements must be *fulfilled* before the system will issue a badge to a learner. @@ -114,7 +114,7 @@ Requirements group is fulfilled if any of its requirements is fulfilled. "OR" logic is applied inside a Group. -.. image:: ../../_static/images/badges/badges-admin-rules-group.png +.. image:: ../../../_static/images/badges/badges-admin-rules-group.png :alt: Badge requirement rules group See :ref:`Configuration examples for Badging`. @@ -131,14 +131,14 @@ To edit/update a Data Rule: - navigate to the Badge Requirement detail page (use ``Change`` inline link); - find the "Data Rules" section and add a new item; -.. image:: ../../_static/images/badges/badges-admin-requirement-rules.png +.. image:: ../../../_static/images/badges/badges-admin-requirement-rules.png :alt: Badge requirement rules edit **Each data rule describes a single expected payload value:** All key paths are generated based on the event type specified for the parent Badge Requirement. -.. image:: ../../_static/images/badges/badges-admin-data-rules.png +.. image:: ../../../_static/images/badges/badges-admin-data-rules.png :alt: Badge requirement data rules 1. **Key path** - payload path to the target attribute @@ -168,7 +168,7 @@ A penalty setup is similar to a badge requirement, but has different effect: it When all penalty rules have been applied, a learner's progress towards a badge is reset. -.. image:: ../../_static/images/badges/badges-admin-penalty-rules.png +.. image:: ../../../_static/images/badges/badges-admin-penalty-rules.png :alt: Badge penalty rules edit Activation @@ -181,7 +181,7 @@ Configured badge template can be activated: Activated badge template starts "working" immediately. -.. image:: ../../_static/images/badges/badges-admin-template-details.png +.. image:: ../../../_static/images/badges/badges-admin-template-details.png :alt: Badge template data structure Credly badge template record includes: diff --git a/docs/badges/configuration/index.rst b/docs/sharing/badges/configuration/index.rst similarity index 100% rename from docs/badges/configuration/index.rst rename to docs/sharing/badges/configuration/index.rst diff --git a/docs/badges/examples.rst b/docs/sharing/badges/examples.rst similarity index 100% rename from docs/badges/examples.rst rename to docs/sharing/badges/examples.rst diff --git a/docs/badges/index.rst b/docs/sharing/badges/index.rst similarity index 98% rename from docs/badges/index.rst rename to docs/sharing/badges/index.rst index 167cdbac1..8a38c7097 100644 --- a/docs/badges/index.rst +++ b/docs/sharing/badges/index.rst @@ -1,5 +1,5 @@ -Badges Information -======================= +Digital Badges +============== The Badges feature allows learners to earn achievements (badges) for their learning activities. @@ -53,4 +53,4 @@ Glossary .. _Credly (by Pearson): https://info.credly.com/ .. _Accredible: https://www.accredible.com/ -.. _Accredible features page: https://www.accredible.com/features \ No newline at end of file +.. _Accredible features page: https://www.accredible.com/features diff --git a/docs/badges/processing.rst b/docs/sharing/badges/processing.rst similarity index 96% rename from docs/badges/processing.rst rename to docs/sharing/badges/processing.rst index e4887275f..b7acfd783 100644 --- a/docs/badges/processing.rst +++ b/docs/sharing/badges/processing.rst @@ -55,7 +55,7 @@ Once all rules of the processed requirement apply, the system: 1. ensures there is the badge progress record for the learner; 2. marks the requirement as fulfilled for the learner; -.. image:: ../_static/images/badges/badges-admin-progress-records.png +.. image:: ../../_static/images/badges/badges-admin-progress-records.png :alt: Badge progress records If a Badge Progress is recognized as completed (all requirements for the badge template are fulfilled), the system initiates the awarding process. @@ -89,7 +89,7 @@ Badges can also be revoked. It's a separate set of rules that need to be set up. 1. Go to Badge Penalties section in admin panel (admin/badges/badge_penalties). -.. image:: ../_static/images/badges/badges-admin-penalty-rules.png +.. image:: ../../_static/images/badges/badges-admin-penalty-rules.png :alt: Badge penalties 2. Select a certain requirement that was previously set up to link penalty diff --git a/docs/badges/quickstart.rst b/docs/sharing/badges/quickstart.rst similarity index 100% rename from docs/badges/quickstart.rst rename to docs/sharing/badges/quickstart.rst diff --git a/docs/badges/settings.rst b/docs/sharing/badges/settings.rst similarity index 100% rename from docs/badges/settings.rst rename to docs/sharing/badges/settings.rst diff --git a/docs/sharing/index.rst b/docs/sharing/index.rst new file mode 100644 index 000000000..716c2566b --- /dev/null +++ b/docs/sharing/index.rst @@ -0,0 +1,23 @@ +Credential Sharing +################## + +Open edX Credentials service supports multiple ways to share and +recognize learner achievements beyond traditional certificates. +Learners and institutions can distribute verified credentials to +third-party platforms, professional networks, and digital wallets. + +This section covers two sharing mechanisms. + +- **Badges** — issue digital badges through providers like Credly + and Accredible. Badges follow the Open Badges standard and can be + displayed on LinkedIn, personal websites, and other platforms. +- **Verifiable Credentials** — issue W3C-compliant verifiable + credentials that learners store in digital wallets. These + credentials are cryptographically signed and independently + verifiable. + +.. toctree:: + :maxdepth: 1 + + badges/index + verifiable_credentials/overview diff --git a/docs/verifiable_credentials/_puml/verifiable_credentials-issuance-sequence.puml b/docs/sharing/verifiable_credentials/_puml/verifiable_credentials-issuance-sequence.puml similarity index 100% rename from docs/verifiable_credentials/_puml/verifiable_credentials-issuance-sequence.puml rename to docs/sharing/verifiable_credentials/_puml/verifiable_credentials-issuance-sequence.puml diff --git a/docs/verifiable_credentials/components.rst b/docs/sharing/verifiable_credentials/components.rst similarity index 96% rename from docs/verifiable_credentials/components.rst rename to docs/sharing/verifiable_credentials/components.rst index 4173ba036..9f4b361e0 100644 --- a/docs/verifiable_credentials/components.rst +++ b/docs/sharing/verifiable_credentials/components.rst @@ -27,12 +27,12 @@ Application section includes: - a list of available issuers - a list of initiated issuance lines -.. image:: ../_static/images/verifiable_credentials-admin-section.png +.. image:: ../../_static/images/verifiable_credentials-admin-section.png :alt: Admin section Currently, only a single Issuer configuration can be active in a moment of time: -.. image:: ../_static/images/verifiable_credentials-issuer-configuration.png +.. image:: ../../_static/images/verifiable_credentials-issuer-configuration.png :alt: Issuance Configurations Issuance configuration describes an Issuer - Organization/University/School on behalf of which verifiable credentials are created. Issuer's ID becomes a part of a verifiable credential and a cryptographic proof is generated with the help of Issuer's private key. Each Issuer has a verbose name. It can be deactivated (checkbox). @@ -44,7 +44,7 @@ Issuance configuration describes an Issuer - Organization/University/School on b Issuance Line Each request for a verifiable credential issuance initiates a separate Issuance Line. It tracks verifiable credential processing life cycle and keeps a connection with a source Open edX user achievement. -.. image:: ../_static/images/verifiable_credentials-issuance-lines.png +.. image:: ../../_static/images/verifiable_credentials-issuance-lines.png :alt: Issuance Lines Issuance line has its unique identifier and additionally includes this information: @@ -60,7 +60,7 @@ Learner Record Microfrontend The Verifiable Credentials feature extends the `Learner Record MFE`_ with additional UI. An extra "Verifiable Credentials" page (tab) becomes available. -.. image:: ../_static/images/verifiable_credentials-learner-record-mfe.png +.. image:: ../../_static/images/verifiable_credentials-learner-record-mfe.png :alt: Verifiable Credentials page 1. Once the Verifiable Credentials feature `is enabled `__ tabs navigation appears diff --git a/docs/verifiable_credentials/configuration.rst b/docs/sharing/verifiable_credentials/configuration.rst similarity index 100% rename from docs/verifiable_credentials/configuration.rst rename to docs/sharing/verifiable_credentials/configuration.rst diff --git a/docs/verifiable_credentials/extensibility.rst b/docs/sharing/verifiable_credentials/extensibility.rst similarity index 100% rename from docs/verifiable_credentials/extensibility.rst rename to docs/sharing/verifiable_credentials/extensibility.rst diff --git a/docs/verifiable_credentials/overview.rst b/docs/sharing/verifiable_credentials/overview.rst similarity index 100% rename from docs/verifiable_credentials/overview.rst rename to docs/sharing/verifiable_credentials/overview.rst diff --git a/docs/verifiable_credentials/quickstart.rst b/docs/sharing/verifiable_credentials/quickstart.rst similarity index 100% rename from docs/verifiable_credentials/quickstart.rst rename to docs/sharing/verifiable_credentials/quickstart.rst diff --git a/docs/verifiable_credentials/storages.rst b/docs/sharing/verifiable_credentials/storages.rst similarity index 86% rename from docs/verifiable_credentials/storages.rst rename to docs/sharing/verifiable_credentials/storages.rst index ff5039594..58ae45856 100644 --- a/docs/verifiable_credentials/storages.rst +++ b/docs/sharing/verifiable_credentials/storages.rst @@ -30,13 +30,13 @@ This explains a generic usage flow for learners. #. Once installed there is initial one-time setup guide. - .. image:: ../_static/images/verifiable_credentials-lcw-setup1.png + .. image:: ../../_static/images/verifiable_credentials-lcw-setup1.png :alt: Learner Credential Wallet setup step 1 :width: 30% - .. image:: ../_static/images/verifiable_credentials-lcw-setup2.png + .. image:: ../../_static/images/verifiable_credentials-lcw-setup2.png :alt: Learner Credential Wallet setup step 2 :width: 30% - .. image:: ../_static/images/verifiable_credentials-lcw-setup3.png + .. image:: ../../_static/images/verifiable_credentials-lcw-setup3.png :alt: Learner Credential Wallet setup step 3 :width: 30% @@ -44,37 +44,37 @@ This explains a generic usage flow for learners. #. On the next step learners are asked for QR code scanning - that's where the LCWallet app starts its flow. Learners use :guilabel:`Scan QR code` option in the mobile application. - .. image:: ../_static/images/verifiable_credentials-lcw-home-empty.png + .. image:: ../../_static/images/verifiable_credentials-lcw-home-empty.png :alt: Learner Credential Wallet empty :width: 30% - .. image:: ../_static/images/verifiable_credentials-lcw-add-credential.png + .. image:: ../../_static/images/verifiable_credentials-lcw-add-credential.png :alt: Learner Credential Wallet add credential :width: 30% - .. image:: ../_static/images/verifiable_credentials-lcw-qrcode-scanner.png + .. image:: ../../_static/images/verifiable_credentials-lcw-qrcode-scanner.png :alt: Learner Credential Wallet QR code scanner :width: 30% #. LCWallet processes QR code, communicates with the Open edX Platform and gets new verifiable credential. If everything is correct, now digital wallet holds the verifiable credential for the given Open edX credential (program certificate). - .. image:: ../_static/images/verifiable_credentials-lcw-accept-credential.png + .. image:: ../../_static/images/verifiable_credentials-lcw-accept-credential.png :alt: Learner Credential Wallet accept credential :width: 30% - .. image:: ../_static/images/verifiable_credentials-lcw-credential-preview.png + .. image:: ../../_static/images/verifiable_credentials-lcw-credential-preview.png :alt: Learner Credential Wallet credential preview :width: 30% - .. image:: ../_static/images/verifiable_credentials-lcw-verification-status.png + .. image:: ../../_static/images/verifiable_credentials-lcw-verification-status.png :alt: Learner Credential Wallet credential status :width: 30% #. From this point learners are free to share their achievements in different ways - .. image:: ../_static/images/verifiable_credentials-lcw-share.png + .. image:: ../../_static/images/verifiable_credentials-lcw-share.png :alt: Learner Credential Wallet share credential :width: 30% - .. image:: ../_static/images/verifiable_credentials-lcw-share-public-link.png + .. image:: ../../_static/images/verifiable_credentials-lcw-share-public-link.png :alt: Learner Credential Wallet share credential with public link :width: 30% - .. image:: ../_static/images/verifiable_credentials-lcw-share-public-link-created.png + .. image:: ../../_static/images/verifiable_credentials-lcw-share-public-link-created.png :alt: Learner Credential Wallet shared with public link credential :width: 30% diff --git a/docs/verifiable_credentials/tech_details.rst b/docs/sharing/verifiable_credentials/tech_details.rst similarity index 97% rename from docs/verifiable_credentials/tech_details.rst rename to docs/sharing/verifiable_credentials/tech_details.rst index 1dab77d6a..06d4709c2 100644 --- a/docs/verifiable_credentials/tech_details.rst +++ b/docs/sharing/verifiable_credentials/tech_details.rst @@ -17,7 +17,7 @@ Events flow Here is how everything happens. -.. image:: ../_static/images/verifiable_credentials-issuance-sequence.png +.. image:: ../../_static/images/verifiable_credentials-issuance-sequence.png :alt: Verifiable Credentials issuance sequence diagram - 1 - Learner navigates to the Learner Record MFE, enters the Verifiable Credentials page. diff --git a/docs/verifiable_credentials/usage.rst b/docs/sharing/verifiable_credentials/usage.rst similarity index 100% rename from docs/verifiable_credentials/usage.rst rename to docs/sharing/verifiable_credentials/usage.rst From 75e1fe5836ea152a3b8729ea8344e9cea5fc3fe8 Mon Sep 17 00:00:00 2001 From: Glib Glugovskiy Date: Wed, 11 Mar 2026 14:57:41 +0100 Subject: [PATCH 3/3] docs: major docs refresh and improvement --- .../badges/configuration/accredible.rst | 164 +------- docs/sharing/badges/configuration/credly.rst | 186 ++-------- .../badges/{ => configuration}/examples.rst | 196 +++++----- docs/sharing/badges/configuration/index.rst | 142 ++++++- docs/sharing/badges/index.rst | 31 +- docs/sharing/badges/management.rst | 89 +++++ docs/sharing/badges/processing.rst | 34 +- docs/sharing/badges/quickstart.rst | 143 +++---- docs/sharing/badges/settings.rst | 349 ++++++++++-------- docs/sharing/index.rst | 4 +- .../verifiable_credentials/components.rst | 35 +- .../verifiable_credentials/configuration.rst | 38 +- .../verifiable_credentials/extensibility.rst | 29 +- .../verifiable_credentials/overview.rst | 60 ++- .../verifiable_credentials/quickstart.rst | 21 +- .../verifiable_credentials/storages.rst | 9 +- .../verifiable_credentials/tech_details.rst | 12 +- docs/sharing/verifiable_credentials/usage.rst | 11 +- 18 files changed, 788 insertions(+), 765 deletions(-) rename docs/sharing/badges/{ => configuration}/examples.rst (74%) create mode 100644 docs/sharing/badges/management.rst diff --git a/docs/sharing/badges/configuration/accredible.rst b/docs/sharing/badges/configuration/accredible.rst index e044bfb21..66b98c311 100644 --- a/docs/sharing/badges/configuration/accredible.rst +++ b/docs/sharing/badges/configuration/accredible.rst @@ -1,172 +1,42 @@ +.. _badges-accredible-configuration: + Accredible Configuration ======================== -.. note:: - - This section provides information on how and where to set up accredible badge groups and configuration. - -The Badges feature is configured in the Credentials admin panel. - -.. image:: ../../../_static/images/badges/badges-admin.png - :alt: Badges administration +.. _badges-accredible-api-configs: Accredible API Configurations ----------------------------- Multiple Accredible API Configurations can be configured. - -**All communication between Open edX Credentials and Accredible service happens on behalf of an Accredible API config.** +All communication between Open edX Credentials and Accredible happens on behalf of an Accredible API config. Go to the Accredible API Configs section in the admin panel and create a new item: -1. to set the name for config; -2. to set the api key, used to sync the Accredible account. +#. Set the **name** for the config. +#. Set the **API key** used to sync the Accredible account. -In case of errors, check the credentials used for the API Config +If errors occur, verify the credentials used for the API Config. Groups ---------------- +------ -*Accredible groups* (badge templates for short) are created in the Accredible dashboard and then, they are retrieved by the Credentials via API. +*Accredible groups* (the Accredible equivalent of badge templates) are created in the Accredible dashboard, then retrieved by the Credentials service via API. Synchronization ~~~~~~~~~~~~~~~ -To synchronize Accredible groups for the API Configuration one should: +To synchronize Accredible groups for an API Configuration: -- navigate "Accredible API Configs" list page; -- select the API Config; -- use ``Sync groups`` action; +#. Navigate to the "Accredible API Configs" list page. +#. Select the API Config. +#. Use the ``Sync groups`` action. .. image:: ../../../_static/images/badges/badges-admin-groups-sync.png - :alt: Accredible groups synchronization - -On success, the system will update the list of Accredible groups: - -- Accredible group records are created inactive (disabled); - -For a group to be considered during the processing it must be configured (to have at least 1 requirement) and activated (enabled) first. - -Badge Requirements ------------------- - - Requirements describe **what** and **how** must happen on the system to earn a badge. - -Badge Requirement(s) specification is a crucial part of group configuration. -At least one badge requirement must be associated with a group. - -Badge Requirements are listed inline on a group detail page. - -.. image:: ../../../_static/images/badges/badges-admin-template-requirements.png - :alt: Credly badge template requirements - -A badge template can have multiple requirements. All badge requirements must be *fulfilled* before the system will issue a badge to a learner. - -Event type -~~~~~~~~~~ - - Describes **what is expected to happen**. - -Available event type subset is pre-configured in the application settings. - -.. note:: - - Technically, any public signal from the `openedx-events`_ library can be used for badge template requirements setup, if it includes user PII (UserData), so users can be identified. - -Rules -~~~~~ - -A list of configured data rules (if any), see "Data Rules". - -Description -~~~~~~~~~~~ - -**Description** is an optional human-readable reminder that describes what the requirement is about. - - Badge Requirement can be **deeper specified** via its Data Rules. - -Group -~~~~~ - -Optional configuration (by default each badge requirement is assigned a separate Group). - -Allows putting 2 or more badge requirements as a Group. -Requirements group is fulfilled if any of its requirements is fulfilled. - - "OR" logic is applied inside a Group. - -.. image:: ../../../_static/images/badges/badges-admin-rules-group.png - :alt: Badge requirement rules group - -See :ref:`Configuration examples for Badging`. - -Data Rules ----------- - - Describes **how it is expected to happen** - -Data Rules detail their parent Badge Requirement based on the expected event payload. - -To edit/update a Data Rule: - -- navigate to the Badge Requirement detail page (use ``Change`` inline link); -- find the "Data Rules" section and add a new item; - -.. image:: ../../../_static/images/badges/badges-admin-requirement-rules.png - :alt: Badge requirement rules edit - -**Each data rule describes a single expected payload value:** - -All key paths are generated based on the event type specified for the parent Badge Requirement. - -.. image:: ../../../_static/images/badges/badges-admin-data-rules.png - :alt: Badge requirement data rules - -1. **Key path** - payload path to the target attribute - - dot-separated string; - - each event type has its unique pre-defined set of key paths; -2. **Operator** - comparison operation to apply between expected and actual values; - - available operators: (payload) - - ``"="`` (equals); - - ``"!="`` (not equals); -3. **Expected value** - an expected value for the target attribute - - payload boolean positive values allowed: ``"true", "True", "yes", "Yes", "+"``; - - payload boolean negative values allowed: ``"false", "False", "no", "No", "-"``; - - -Please, see :ref:`Configuration examples for Badging` for clarity. - -Badge Penalties ---------------- - - Penalties allow badge progress resetting based on user activity. - -Badge penalties are optional. -There could be 0 or more badge penalties configured for a badge template. - -Each badge penalty is *targeted* to 1 or more badge requirements. -A penalty setup is similar to a badge requirement, but has different effect: it decreases badge progress for a user. - -When all penalty rules have been applied, a learner's progress towards a badge is reset. - -.. image:: ../../../_static/images/badges/badges-admin-penalty-rules.png - :alt: Badge penalty rules edit - -Activation ----------- - -Configured group can be activated: - -- navigate to the group detail page; -- check ``Is active`` checkbox; - - Activated groups start "working" immediately. + :alt: Accredible groups synchronization -Accredible group record includes: +On success, the system updates the list of Accredible groups. -1. Core credential attributes; -2. Badge template credential attributes; -3. Accredible service attributes (dashboard link); -4. Configured requirements; +- New group records are created inactive (disabled). -.. _openedx-events: https://github.com/openedx/openedx-events \ No newline at end of file +Configure requirements (see :ref:`badges-configuration-requirements`) and activate the group (see :ref:`badges-configuration-activation`) before it takes effect. diff --git a/docs/sharing/badges/configuration/credly.rst b/docs/sharing/badges/configuration/credly.rst index 33c6bb48e..2562694a1 100644 --- a/docs/sharing/badges/configuration/credly.rst +++ b/docs/sharing/badges/configuration/credly.rst @@ -1,194 +1,60 @@ +.. _badges-credly-configuration: + Credly Configuration ==================== -.. note:: - - This section provides information on how and where to set up badge templates and organizations. - -The Badges feature is configured in the Credentials admin panel. - -.. image:: ../../../_static/images/badges/badges-admin.png - :alt: Badges administration +.. _badges-credly-organizations: Credly Organizations -------------------- Multiple Credly Organizations can be configured. - -**All communication between Open edX Credentials and Credly service happens on behalf of a Credly Organization.** +All communication between Open edX Credentials and Credly happens on behalf of a Credly Organization. Go to the Credly Organization section in the admin panel and create a new item: -1. to set the UUID use your Credly Organization identifier; -2. to set the authorization token, used to sync the Credly Organization. +#. Set the **UUID** to your Credly Organization identifier. +#. Set the **authorization token** used to sync the Credly Organization. -Check: the system pulls the Organization's details and updates its name. +The system pulls the Organization's details and updates its name. +If errors occur, verify the credentials used for the Organization. -In case of errors, check the credentials used for the Organization - -Badge templates +Badge Templates --------------- -*Credly badge templates* (badge templates for short) are created in the Credly Organization's dashboard and then, if published, they are retrieved by the Credentials via API. +*Credly badge templates* are created in the Credly Organization's dashboard. +Once published, they are retrieved by the Credentials service via API. Webhooks -~~~~~~~~~~~~~~~ +~~~~~~~~ .. note:: - Webhooks is a connection with Credly and external platform that allows your server to be notified about events occurring within Credly. + Webhooks connect Credly with an external platform so your server is notified about events within Credly. -Webhooks are set up on Credly management dashboard as Credly is a main initiator of the synchronization. +Webhooks are set up on the Credly management dashboard — Credly initiates the synchronization. -You should be able to select an action from the list so that whenever the specified action occurs internally, the external system is alerted. - -Without this synchronization, the external system will not be notified of any significant changes (e.g. a badge template update, or a badge template has been archived) and may incorrectly issue erroneous or outdated badges. +Select an action from the list so that whenever the specified action occurs, your system is notified. +Without this synchronization, the external system will not learn about changes (e.g. a template update or archival) and may issue outdated badges. Synchronization ~~~~~~~~~~~~~~~ -To synchronize Credly badge templates for the Organization one should: +To synchronize Credly badge templates for an Organization: -- navigate "Credly badge templates" list page; -- select the Organization; -- use ``Sync organization badge templates`` action; +#. Navigate to the "Credly Organizations" list page. +#. Select the Organization. +#. Use the ``Sync organization badge templates`` action. .. image:: ../../../_static/images/badges/badges-admin-credly-templates-sync.png - :alt: Credly badge templates synchronization + :alt: Credly badge templates synchronization -On success, the system will update the list of Credly badge templates for the Organization: +On success, the system updates the list of badge templates for that Organization. -- only badge templates with ``active`` state are pulled; -- Credly badge template records are created inactive (disabled); +- Only badge templates with ``active`` state are pulled. +- New badge template records are created inactive (disabled). .. image:: ../../../_static/images/badges/badges-admin-credly-templates-list.png - :alt: Credly badge templates list - -For a badge template to be considered during the processing it must be configured (to have at least 1 requirement) and activated (enabled) first. - -Badge Requirements ------------------- - - Requirements describe **what** and **how** must happen on the system to earn a badge. - -Badge Requirement(s) specification is a crucial part of badge template configuration. -At least one badge requirement must be associated with a badge template. - -Badge Requirements are listed inline on a badge template detail page. - -.. image:: ../../../_static/images/badges/badges-admin-template-requirements.png - :alt: Credly badge template requirements - -A badge template can have multiple requirements. All badge requirements must be *fulfilled* before the system will issue a badge to a learner. - -Event type -~~~~~~~~~~ - - Describes **what is expected to happen**. - -Available event type subset is pre-configured in the application settings. - -.. note:: - - Technically, any public signal from the `openedx-events`_ library can be used for badge template requirements setup, if it includes user PII (UserData), so users can be identified. - -Rules -~~~~~ - -A list of configured data rules (if any), see "Data Rules". - -Description -~~~~~~~~~~~ - -**Description** is an optional human-readable reminder that describes what the requirement is about. - - Badge Requirement can be **deeper specified** via its Data Rules. - -Group -~~~~~ - -Optional configuration (by default each badge requirement is assigned a separate Group). - -Allows putting 2 or more badge requirements as a Group. -Requirements group is fulfilled if any of its requirements is fulfilled. - - "OR" logic is applied inside a Group. - -.. image:: ../../../_static/images/badges/badges-admin-rules-group.png - :alt: Badge requirement rules group - -See :ref:`Configuration examples for Badging`. - -Data Rules ----------- - - Describes **how it is expected to happen** - -Data Rules detail their parent Badge Requirement based on the expected event payload. - -To edit/update a Data Rule: - -- navigate to the Badge Requirement detail page (use ``Change`` inline link); -- find the "Data Rules" section and add a new item; - -.. image:: ../../../_static/images/badges/badges-admin-requirement-rules.png - :alt: Badge requirement rules edit - -**Each data rule describes a single expected payload value:** - -All key paths are generated based on the event type specified for the parent Badge Requirement. - -.. image:: ../../../_static/images/badges/badges-admin-data-rules.png - :alt: Badge requirement data rules - -1. **Key path** - payload path to the target attribute - - dot-separated string; - - each event type has its unique pre-defined set of key paths; -2. **Operator** - comparison operation to apply between expected and actual values; - - available operators: (payload) - - ``"="`` (equals); - - ``"!="`` (not equals); -3. **Expected value** - an expected value for the target attribute - - payload boolean positive values allowed: ``"true", "True", "yes", "Yes", "+"``; - - payload boolean negative values allowed: ``"false", "False", "no", "No", "-"``; - - -Please, see :ref:`Configuration examples for Badging` for clarity. - -Badge Penalties ---------------- - - Penalties allow badge progress resetting based on user activity. - -Badge penalties are optional. -There could be 0 or more badge penalties configured for a badge template. - -Each badge penalty is *targeted* to 1 or more badge requirements. -A penalty setup is similar to a badge requirement, but has different effect: it decreases badge progress for a user. - -When all penalty rules have been applied, a learner's progress towards a badge is reset. - -.. image:: ../../../_static/images/badges/badges-admin-penalty-rules.png - :alt: Badge penalty rules edit - -Activation ----------- - -Configured badge template can be activated: - -- navigate to the badge template detail page; -- check ``Is active`` checkbox; - - Activated badge template starts "working" immediately. - -.. image:: ../../../_static/images/badges/badges-admin-template-details.png - :alt: Badge template data structure - -Credly badge template record includes: - -1. Core credential attributes; -2. Badge template credential attributes; -3. Credly service attributes (state, dashboard link); -4. Configured requirements; + :alt: Credly badge templates list -.. _openedx-events: https://github.com/openedx/openedx-events \ No newline at end of file +Configure requirements (see :ref:`badges-configuration-requirements`) and activate the template (see :ref:`badges-configuration-activation`) before it takes effect. diff --git a/docs/sharing/badges/examples.rst b/docs/sharing/badges/configuration/examples.rst similarity index 74% rename from docs/sharing/badges/examples.rst rename to docs/sharing/badges/configuration/examples.rst index 9be07a535..d69816606 100644 --- a/docs/sharing/badges/examples.rst +++ b/docs/sharing/badges/configuration/examples.rst @@ -1,36 +1,38 @@ +:orphan: + .. _Configuration examples for Badging: -Configuration examples for Badging -=================================== +Configuration Examples +====================== -These examples will show how to configure requirements and ``data rules`` for necessary use cases. +These examples show how to configure requirements and data rules for common use cases. .. note:: + Requirements in the **same group** use OR logic - any one of them fulfills the group. + Requirements in **different groups** use AND logic - all groups must be fulfilled. Any of the following examples can be combined for more specific use cases. +Course Completion +----------------- -Implemented use cases ----------------------- - - -1. ANY COURSE GRADE update -~~~~~~~~~~~~~~~~~~~~~~~~~~ +ANY COURSE GRADE Update +~~~~~~~~~~~~~~~~~~~~~~~ - Not that useful. Any interaction (e.g. submit button click) with gradable block in any course leads to a badge. + Triggers on any gradable interaction (e.g. submit button click) in any course. Rarely useful on its own. -1. **Requirement 1**: +- **Requirement 1**: a. event type: ``org.openedx.learning.course.passing.status.updated.v1`` b. description: ``On any grade update.`` -2. ANY COURSE completion -~~~~~~~~~~~~~~~~~~~~~~~~ +ANY COURSE Completion +~~~~~~~~~~~~~~~~~~~~~ - Requires **passing grade** for any course. Once course'd grade becomes "passing" after gradable problem submission, + Requires **passing grade** for any course. Once a course grade becomes "passing" after a gradable problem submission, a badge is awarded. -1. **Requirement 1**: +- **Requirement 1**: a. event type: ``org.openedx.learning.course.passing.status.updated.v1`` b. description: ``On any (not CCX) course completion.`` c. **Data rule 1**: @@ -39,26 +41,12 @@ Implemented use cases iii. value: ``true`` -3. ANY CCX course completion -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - - Requires **passing grade** for any CCX course. - -1. **Requirement 1**: - a. event type: ``org.openedx.learning.ccx.course.passing.status.updated.v1`` - b. description: ``On any CCX course completion.`` - c. **Data rule 1**: - i. key path: ``is_passing`` - ii. operator: ``equals`` - iii. value: ``true`` - - -4. ANY COURSE completion EXCEPT a specific course -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +ANY COURSE Completion EXCEPT a Specific Course +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Requires **passing grade** for any course **excluding** the "Demo" course. -1. **Requirement 1**: +- **Requirement 1**: a. event type: ``org.openedx.learning.course.passing.status.updated.v1`` b. description: ``On any course completion, but not the "Demo" course.`` c. **Data rule 1**: @@ -71,12 +59,12 @@ Implemented use cases iii. value: ``course-v1:edX+DemoX+Demo_Course`` -5. SPECIFIC COURSE completion -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +SPECIFIC COURSE Completion +~~~~~~~~~~~~~~~~~~~~~~~~~~ Requires **passing grade** for exact course ("Demo" course). -1. **Requirement 1**: +- **Requirement 1**: a. event type: ``org.openedx.learning.course.passing.status.updated.v1`` b. description: ``On the Demo course completion.`` c. **Data rule 1**: @@ -89,13 +77,13 @@ Implemented use cases iii. value: ``course-v1:edX+DemoX+Demo_Course`` -6. MULTIPLE SPECIFIC COURSES completion -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +MULTIPLE SPECIFIC COURSES Completion +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ **All** specified courses must be completed. Different requirement groups force each requirement to be fulfilled. -1. **Requirement 1**: +- **Requirement 1**: a. event type: ``org.openedx.learning.course.passing.status.updated.v1`` b. description: ``On the "Demo" course completion.`` c. group: ``A`` @@ -108,7 +96,7 @@ Implemented use cases ii. operator: ``equals`` iii. value: ``course-v1:edX+DemoX+Demo_Course`` -2. **Requirement 2**: +- **Requirement 2**: a. event type: ``org.openedx.learning.course.passing.status.updated.v1`` b. description: ``On the "Other" course completion.`` c. group: ``B`` @@ -122,12 +110,63 @@ Implemented use cases iii. value: ``course-v1:edX+DemoX+OTHER_Course`` -7. SPECIFIC CCX course completion -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +ONE OF MULTIPLE SPECIFIC COURSES Completion +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + At least a single from the specified courses must be completed. + Grouped requirements are processed as **"ANY FROM A GROUP"**. + +- **Requirement 1**: + a. event type: ``org.openedx.learning.course.passing.status.updated.v1`` + b. description: ``On the "Demo" course completion.`` + c. group: ``A`` + d. **Data rule 1**: + i. key path: ``is_passing`` + ii. operator: ``equals`` + iii. value: ``true`` + e. **Data rule 2**: + i. key path: ``course.course_key`` + ii. operator: ``equals`` + iii. value: ``course-v1:edX+DemoX+Demo_Course`` + +- **Requirement 2**: + a. event type: ``org.openedx.learning.course.passing.status.updated.v1`` + b. description: ``On the "Other" course completion.`` + c. group: ``A`` + d. **Data rule 1**: + i. key path: ``is_passing`` + ii. operator: ``equals`` + iii. value: ``true`` + e. **Data rule 2**: + i. key path: ``course.course_key`` + ii. operator: ``equals`` + iii. value: ``course-v1:edX+DemoX+OTHER_Course`` + + +CCX Course Completion +--------------------- + + +ANY CCX Course Completion +~~~~~~~~~~~~~~~~~~~~~~~~~ + + Requires **passing grade** for any CCX course. + +- **Requirement 1**: + a. event type: ``org.openedx.learning.ccx.course.passing.status.updated.v1`` + b. description: ``On any CCX course completion.`` + c. **Data rule 1**: + i. key path: ``is_passing`` + ii. operator: ``equals`` + iii. value: ``true`` + + +SPECIFIC CCX Course Completion +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Requires **passing grade** for exact CCX course ("Demo CCX1" course). -1. **Requirement 1**: +- **Requirement 1**: a. event type: ``org.openedx.learning.ccx.course.passing.status.updated.v1`` b. description: ``On the Demo CCX1 course completion.`` c. **Data rule 1**: @@ -139,12 +178,12 @@ Implemented use cases ii. operator: ``equals`` iii. value: ``ccx-v1:edX+DemoX+Demo_Course+ccx@1`` -8. ANY CCX course completion ON a SPECIFIC MASTER course -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +ANY CCX Course Completion on a Specific Master Course +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Requires **passing grade** for any "child" CCX course that based on the master "Demo" course. -1. **Requirement 1**: +- **Requirement 1**: a. event type: ``org.openedx.learning.ccx.course.passing.status.updated.v1`` b. description: ``On any Demo CCX course completion.`` c. **Data rule 1**: @@ -156,13 +195,12 @@ Implemented use cases ii. operator: ``equals`` iii. value: ``course-v1:edX+DemoX+Demo_Course`` -9. ANY CCX course completion ON a SPECIFIC MASTER course EXCEPT a SPECIFIC CCX course -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +ANY CCX Course Completion on a Specific Master Course Except a Specific CCX Course +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Complicated. Requires **passing grade** for **any "child" CCX course** that based on the master "Demo" course, **excluding** the "Demo CCX2" course. -1. **Requirement 1**: +- **Requirement 1**: a. event type: ``org.openedx.learning.ccx.course.passing.status.updated.v1`` b. description: ``On any Demo CCX course completion.`` c. **Data rule 1**: @@ -178,45 +216,13 @@ Implemented use cases ii. operator: ``not equals`` iii. value: ``ccx-v1:edX+DemoX+Demo_Course+ccx@2`` -10. ONE OF MULTIPLE SPECIFIC COURSES completion -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - - At least a single from the specified courses must be completed. - Grouped requirements are processed as **"ANY FROM A GROUP"**. - -1. **Requirement 1**: - a. event type: ``org.openedx.learning.course.passing.status.updated.v1`` - b. description: ``On the "Demo" course completion.`` - c. group: ``A`` - d. **Data rule 1**: - i. key path: ``is_passing`` - ii. operator: ``equals`` - iii. value: ``true`` - e. **Data rule 2**: - i. key path: ``course.course_key`` - ii. operator: ``equals`` - iii. value: ``course-v1:edX+DemoX+Demo_Course`` - -2. **Requirement 2**: - a. event type: ``org.openedx.learning.course.passing.status.updated.v1`` - b. description: ``On the "Other" course completion.`` - c. group: ``A`` - d. **Data rule 1**: - i. key path: ``is_passing`` - ii. operator: ``equals`` - iii. value: ``true`` - e. **Data rule 2**: - i. key path: ``course.course_key`` - ii. operator: ``equals`` - iii. value: ``course-v1:edX+DemoX+OTHER_Course`` - -11. SPECIFIC MASTER course OR ANY of its CCX courses EXCEPT a SPECIFIC CCX course completion -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Specific Master Course OR Any of Its CCX Courses Except a Specific CCX Course +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Here requirements 1 and 2 are grouped, so any of them lead to a badge. -1. **Requirement 1**: +- **Requirement 1**: a. event type: ``org.openedx.learning.course.passing.status.updated.v1`` b. description: ``On the "Demo" course completion OR...`` c. group: ``A`` @@ -229,7 +235,7 @@ Implemented use cases ii. operator: ``equals`` iii. value: ``course-v1:edX+DemoX+Demo_Course`` -2. **Requirement 2**: +- **Requirement 2**: a. event type: ``org.openedx.learning.ccx.course.passing.status.updated.v1`` b. description: ``...OR any Demo CCX courses completion EXCLUDING CCX3.`` c. group: ``A`` @@ -248,12 +254,16 @@ Implemented use cases ----- -Future work ------------ +Potential Use Cases +------------------- + +The following ideas are not yet implemented. If you have a use case for any of them, start a conversation on the `Open edX discussion forum`_. + +- Events set extension (e.g. "Email activation", "Profile data completion", "Course section completion") +- Repetitive events (e.g. "5 arbitrary courses completion") +- Prerequisite events (e.g. "5 specific courses completion in a specified order") +- Time-ranged events (e.g. "Arbitrary course completion during February 2022") +- Badge dependencies (e.g. "Badge A + Badge B = Badge C") +- Multiple same badge earning (e.g. "3 arbitrary course completions make badge earned x3") -1. Events set extension (e.g. "Email activation", "Profile data completion", "Course section completion", ...); -2. Repetitive events (e.g. "5 arbitrary courses completion"); -3. Prerequisite events (e.g. "5 specific courses completion in a specified order"); -4. Time-ranged event (e.g. "Arbitrary course completion during the February 2022"); -5. Badge dependencies (e.g. "Badge A + Badge B = Badge C"); -6. Multiple times same badge earning (e.g. "3 arbitrary course completions make badge earned x3"); +.. _Open edX discussion forum: https://discuss.openedx.org/ diff --git a/docs/sharing/badges/configuration/index.rst b/docs/sharing/badges/configuration/index.rst index 6fed4f3ec..2a21cde3c 100644 --- a/docs/sharing/badges/configuration/index.rst +++ b/docs/sharing/badges/configuration/index.rst @@ -1,10 +1,142 @@ +.. _badges-configuration: + Badging Configuration -====================== +===================== + +Badge templates, requirements, rules, and penallties are configured in the Credentials admin panel. +Each badge template needs at least one requirement and must be activated before it takes effect. + +.. note:: + + Accredible uses the term "group" for what Credly calls a "badge template." This section uses "badge template" as the generic term for both. + +.. image:: ../../../_static/images/badges/badges-admin.png + :alt: Badges administration + +Provider Setup +-------------- + +Provider setup (organization credentials, template synchronization) differs per badging provider. .. toctree:: - :maxdepth: 1 + :maxdepth: 1 + + credly + accredible + +.. _badges-configuration-requirements: + +Badge Requirements +------------------ + +Requirements describe what must happen for a learner to earn a badge. +At least one requirement must be associated with a badge template. + +Badge requirements are listed inline on the badge template detail page. + +.. image:: ../../../_static/images/badges/badges-admin-template-requirements.png + :alt: Badge template requirements + +A badge template can have multiple requirements. +All requirements must be *fulfilled* before the system issues a badge. + +.. _badges-configuration-groups: + +Each requirement has the following fields. + +- **Event type** - the event that must occur. Available event types are pre-configured in the application settings. +- **Rules** - a list of configured data rules (if any). See :ref:`badges-configuration-data-rules`. +- **Description** - an optional human-readable reminder about the requirement's purpose. +- **Group** - by default each requirement belongs to its own group. You can assign two or more requirements to the same group - the group is fulfilled when *any* of its requirements is fulfilled ("OR" logic inside a group). + +.. image:: ../../../_static/images/badges/badges-admin-rules-group.png + :alt: Badge requirement rules group + +.. note:: + + Any public signal from the `openedx-events`_ library can be used, provided it includes user PII (``UserData``) so learners can be identified. + +See :ref:`Configuration examples for Badging`. + +.. _badges-configuration-data-rules: + +Data Rules +---------- + +Data rules narrow a badge requirement based on the expected event payload. + +To add or edit a data rule: + +#. Navigate to the badge requirement detail page (use the ``Change`` inline link). +#. Find the "Data Rules" section and add a new item. + +.. image:: ../../../_static/images/badges/badges-admin-requirement-rules.png + :alt: Badge requirement rules edit + +Each data rule describes a single expected payload value. +Key paths are generated from the event type of the parent requirement. + +.. image:: ../../../_static/images/badges/badges-admin-data-rules.png + :alt: Badge requirement data rules + +.. list-table:: + :widths: 20 80 + :header-rows: 1 + + * - Field + - Description + * - **Key path** + - Dot-separated path to the target attribute. Each event type has a pre-defined set of key paths. + * - **Operator** + - Comparison operation: ``"="`` (equals) or ``"!="`` (not equals). + * - **Expected value** + - The value to compare against. Boolean positives: ``"true"``, ``"True"``, ``"yes"``, ``"Yes"``, ``"+"``. Boolean negatives: ``"false"``, ``"False"``, ``"no"``, ``"No"``, ``"-"``. + +See :ref:`Configuration examples for Badging` for details. + +.. _badges-configuration-penalties: + +Badge Penalties +--------------- + +Penalties reset badge progress based on learner activity. +They are optional - a badge template can have zero or more. + +Each penalty targets one or more badge requirements. +A penalty uses the same structure as a requirement, but *decreases* progress instead of advancing it. +When all penalty rules match, the learner's progress toward the badge resets. + +.. image:: ../../../_static/images/badges/badges-admin-penalty-rules.png + :alt: Badge penalty rules edit + +.. _badges-configuration-activation: + +Activation +---------- + +After configuring requirements, activate the badge template: + +#. Navigate to the badge template detail page. +#. Check the ``Is active`` checkbox. + +.. important:: + + An activated badge template starts working immediately. + +.. image:: ../../../_static/images/badges/badges-admin-template-details.png + :alt: Badge template detail page + +.. list-table:: + :widths: 50 50 + :header-rows: 0 - credly - accredible + * - Core credential attributes + - Shared across all credential types. + * - Badge template credential attributes + - Specific to badges. + * - Provider-specific attributes + - State, dashboard link, etc. Varies by provider (see :ref:`badges-credly-configuration` or :ref:`badges-accredible-configuration`). + * - Configured requirements + - See :ref:`badges-configuration-requirements`. -.. _Credly (by Pearson): https://info.credly.com/ \ No newline at end of file +.. _openedx-events: https://github.com/openedx/openedx-events diff --git a/docs/sharing/badges/index.rst b/docs/sharing/badges/index.rst index 8a38c7097..d932aa20f 100644 --- a/docs/sharing/badges/index.rst +++ b/docs/sharing/badges/index.rst @@ -3,10 +3,10 @@ Digital Badges The Badges feature allows learners to earn achievements (badges) for their learning activities. -- **Badge Template** is another kind of **credential**. -- **Badge** is another kind of **user credential**. +- A **badge template** (called "group" in Accredible) defines a badge's design, name, and awarding rules. +- A **badge** is the credential a learner earns when they fulfill all requirements of a badge template. -Current Badges version is highly integrated with the `Credly (by Pearson)`_ and `Accredible`_ services, but it is fully prepared to be used separately. +The Badges feature integrates with `Credly (by Pearson)`_ and `Accredible`_ services, but can also be used independently. What is Credly? --------------- @@ -14,31 +14,28 @@ What is Credly? **Credly** is an end-to-end solution for creating, issuing, and managing digital Credentials. Organizations use **Credly** to recognize their learners' achievements. Learners can store badges in their Credly profile to visualize their professional success - which courses were completed and when. -Badges provide employers and peers concrete evidence of what learners have -accomplished in order to earn their credential and what they are now capable of. -Digital badges are a great way to motivate learning and display a learner's -subsequent achievements. +Badges provide employers and peers concrete evidence of what learners have accomplished to earn their credential and what they are capable of. -Badges are typically finer-grained than a traditional course certificate. They -are meant to introduce game mechanics to have more frequent sources of -motivation than one would get from a cumulative certificate. +Badges are typically finer-grained than a traditional course certificate. They are meant to introduce game mechanics to have more frequent sources of motivation than one would get from a cumulative certificate. What is Accredible? -------------------- -**Accredible** allows for the design and issuance of verifiable digital badges and -certificates that showcase acquired skills, earning criteria, and evidence of -learning. Learn more about Accredible on the `Accredible features page`_. +**Accredible** allows for the design and issuance of verifiable digital badges and certificates that showcase acquired skills, earning criteria, and evidence of learning. Learn more about Accredible on the `Accredible features page`_. Glossary -------- -1. **Badge template** – a template of a badge (with design, name, and description) that will be used in settings to set up special rules to create a badge for users to receive on the platform. +1. **Badge template** - a template for a badge (with design, name, and description) used to set up rules for awarding badges to learners. Called "group" in Accredible. -2. **Authorization token** – It's a temporary key that verifies identity and authorizes resource access. A token can be computer-generated or hardware-based. A valid token allows a user to retain access to an online service or web application until the token expires. +2. **Requirement** - a condition that must be met to earn a badge, tied to a specific event type (e.g. course completion). -3. **UUID** – Universally Unique Identifier – is a value used to identify an object or entity on the internet uniquely. Depending on the specific mechanisms used, a UUID is either guaranteed to be different or is, at least, extremely likely to be different from any other UUID generated. +3. **Data rule** - a filter on a requirement's event payload (e.g. ``course.course_key equals course-v1:edX+DemoX``). + +4. **Group** - requirements in the same group use OR logic (any one fulfills the group). Requirements in different groups use AND logic. + +5. **Penalty** - a rule that resets badge progress when a learner no longer meets a requirement (e.g. grade drops below passing). ---- @@ -48,8 +45,8 @@ Glossary quickstart settings configuration/index - examples processing + management .. _Credly (by Pearson): https://info.credly.com/ .. _Accredible: https://www.accredible.com/ diff --git a/docs/sharing/badges/management.rst b/docs/sharing/badges/management.rst new file mode 100644 index 000000000..df7847661 --- /dev/null +++ b/docs/sharing/badges/management.rst @@ -0,0 +1,89 @@ +Managing Badges +=============== + +Synchronizing Badge Templates +----------------------------- + +Badge templates (Credly) and groups (Accredible) are created on +the provider's side and then pulled into the Credentials service +through a sync action in the admin panel. + +For **Credly**: select one or more organizations on the "Credly +Organizations" list page and run the ``Sync organization badge +templates`` action. Only badge templates with ``active`` state on +Credly are pulled. See :ref:`badges-credly-configuration` for +details. + +For **Accredible**: select one or more configurations on the +"Accredible API Configs" list page and run the ``Sync groups`` +action. See :ref:`badges-accredible-configuration` for details. + +.. note:: + + Synchronized templates and groups are created **inactive** by + default. Configure requirements and activate them before they + take effect. See :ref:`badges-configuration-activation`. + +Badge Progress +-------------- + +Current badge progress is visible in the "Badge progress records" +section of the Credentials admin panel. + +Badge templates can have more than one requirement, so there can +be partially completed badges. See :ref:`badges-processing` for +details on how progress is tracked. + +Awarded Credentials +------------------- + +Earned badges are listed in the "Credly badges" or "Accredible badges" section of the admin panel. + +.. note:: + + Each badge is an extended version of a user credential record. + +Once badge progress is complete (all requirements are *fulfilled*), +the system awards the badge. See :ref:`badges-processing` for the +full awarding pipeline. + +The system: + +1. creates an internal user credential (CredlyBadge or AccredibleBadge); +2. notifies about the badge awarding (public signal); +3. requests the Credly or Accredible service to issue the badge (API request). + +Issued Badges +------------- + +After a badge is awarded internally, the system sends an API +request to Credly or Accredible to issue the badge on their +platform. + +On successful issuing, the badge record in the admin panel is +updated with: + +1. **external UUID** - the identifier assigned by Credly or Accredible; +2. **external state** - the badge status on the provider's side (e.g. ``accepted``). + +The issued badge then appears in the provider's dashboard (Credly +or Accredible) and is visible to the learner. + +Badge Template Withdrawal +------------------------- + +Deactivate a badge template by unchecking the ``is active`` checkbox +on its edit page. See :ref:`badges-configuration` for activation details. + +Inactive badge templates are ignored during processing. + +.. seealso:: + + :ref:`badges-configuration` + Configure badge templates, requirements, and data rules. + + :ref:`badges-settings` + Feature switches and integration settings. + + :ref:`badges-processing` + How incoming events are processed and badges are awarded. diff --git a/docs/sharing/badges/processing.rst b/docs/sharing/badges/processing.rst index b7acfd783..7318b9264 100644 --- a/docs/sharing/badges/processing.rst +++ b/docs/sharing/badges/processing.rst @@ -1,7 +1,9 @@ +.. _badges-processing: + Badges Processing ================== -Incoming events async processing happens in a separate event bus consumer process(es). +Incoming events are processed asynchronously in a separate event bus consumer process. See the Event Bus documentation for details. @@ -12,8 +14,8 @@ Events subscription 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). +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 @@ -48,7 +50,7 @@ Current learners' badge progress is stored in the ``Badge Progress`` record. .. note:: - Since badge templates can have more than one requirement, the system should track intermediate progresses as well. + Badge templates can have more than one requirement, so the system tracks intermediate progress. Once all rules of the processed requirement apply, the system: @@ -76,29 +78,21 @@ On badge progress completion, the system: .. note:: - 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**. + The Badges application implements extended ``UserCredential`` versions (CredlyBadge and AccredibleBadge) to track external issuing state. Once a badge is successfully issued, the corresponding record is updated with its external UUID and state. .. _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 +.. _default settings: settings.html Badge revocation ---------------- -Badges can also be revoked. It's a separate set of rules that need to be set up. - -1. Go to Badge Penalties section in admin panel (admin/badges/badge_penalties). - -.. image:: ../../_static/images/badges/badges-admin-penalty-rules.png - :alt: Badge penalties - -2. Select a certain requirement that was previously set up to link penalty - a. To know how to set up badge template requirements, go to the `Configuration`_ section. - -3. Note that all penalties have to be linked to a certain requirement, so that when that requirement is not fulfilled, system would know when to revoke the badge. +Badges can be revoked through badge penalties - rules that reset progress when a requirement is no longer fulfilled. See the :ref:`badges-configuration` section for penalty setup. -.. _Configuration: configuration.html +Each penalty is linked to a specific requirement. When the penalty conditions match, the system resets the learner's progress for that requirement. -When a learner's badge is revoked by Credly, the Credentials IDA will be notified and will update its internal records. The status of the badge will change from `awarded` to `revoked` upon successful revocation. +When a badge is revoked, the system updates its internal records. +For Credly, status changes from ``awarded`` to ``revoked``. +For Accredible, status changes from ``awarded`` to ``expired``. -The badge cannot be reissued once it has been revoked. +A badge cannot be reissued once revoked. diff --git a/docs/sharing/badges/quickstart.rst b/docs/sharing/badges/quickstart.rst index c167de902..19ba481b2 100644 --- a/docs/sharing/badges/quickstart.rst +++ b/docs/sharing/badges/quickstart.rst @@ -1,14 +1,14 @@ Badges Operator Quick Start -============================ +=========================== + +Currently Open edX supports two badge services: Credly and Accredible. .. note:: - This section includes brief information about the feature – what to start with; where to set up credentials, etc. + Both providers use the same concept - a **badge template** defines the badge design and awarding rules. Credly calls these "badge templates"; Accredible calls them "groups." This guide uses "badge template" as the generic term. -Currently Open edX supports two badge services: Credly and Accredible. - -0. Prerequisites – service account ----------------------------------- +Prerequisites +------------- To start using this feature a Credly or Accredible account is necessary. @@ -24,12 +24,12 @@ For Accredible: 1. Register on Accredible and create your account. 2. Create at least 1 group. -1. Enable feature ------------------ +Enable feature +-------------- -Badges feature is optional and it is disabled by default. So, it must be enabled to be accessible. +Badges feature is optional and disabled by default. It must be enabled to be accessible. -.. code-block:: +.. code-block:: python # LMS service: FEATURES["BADGES_ENABLED"] = True @@ -37,58 +37,60 @@ Badges feature is optional and it is disabled by default. So, it must be enabled # Credentials service: BADGES_ENABLED = True -2. Configure integration -------------------------------- +Configure integration +--------------------- .. note:: - For detailed information, go to the `Configuration`_ section. + For detailed information, go to the :ref:`badges-configuration` section. Go to the Credentials service admin panel and configure the integration with the service: Credly ------- +~~~~~~ + +1. In the admin panel go to ``/admin/badges/credlyorganization/`` to add Credly Organization. -1. In the admin panel go to /admin/badges/credly_organization to add Credly Organization. - a. Add UUID (unique identifier) for the Credly organization - b. Add the authorization token of the Credly organization. + a. Add UUID (unique identifier) for the Credly organization + b. Add the authorization token of the Credly organization. -Please note that UUID and authorization token will be given to you during the creation of the Credly Organization on the Credly side +UUID and authorization token are provided when you create the Credly Organization on the Credly side. Check: the system pulls the Organization's data and updates its name. Accredible ------------ +~~~~~~~~~~ 1. Retrieve API Key from Accredible account settings. Go to the Accredible account settings -> Manage API Keys and create a new API Key. 2. In the admin panel go to ``/admin/badges/accredibleapiconfig`` to add Accredible Group. - a. Add API Key - b. Add name for configuration -.. _Configuration: configuration.html + a. Add API Key + b. Add name for configuration -3. Synchronize badge templates ------------------------------- - Note: For detailed information, go to the `Configuration`_ section. +Synchronize badge templates +--------------------------- + +.. note:: + + For detailed information, go to the :ref:`badges-configuration` section. Credly ------- +~~~~~~ -From the “Credly Organizations” list, select the Organization(s) you want to use and select ``Sync organization badge templates`` action. +From the "Credly Organizations" list, select the Organization(s) you want to use and select ``Sync organization badge templates`` action. -The system pulls the list of badge templates from the Credly Organization. Navigate to the “Credly badge templates” list and check newly created templates. +The system pulls the list of badge templates from the Credly Organization. Navigate to the "Credly badge templates" list and check newly created templates. Accredible ----------- -From the Accredible API Configurations list, select the Configuration(s) you want to use and select ``Sync groups`` action. +~~~~~~~~~~ -The system pulls the list of groups from the Accredible account. Navigate to the “Accredible groups” list and check newly created groups. +From the Accredible API Configurations list, select the Configuration(s) you want to use and select ``Sync groups`` action. -.. _Configuration: configuration.html +The system pulls the list of groups from the Accredible account. Navigate to the "Accredible groups" list and check newly created groups. -4. Setup badge requirements ---------------------------- +Setup badge requirements +------------------------ .. note:: @@ -96,22 +98,26 @@ The system pulls the list of groups from the Accredible account. Navigate to the The crucial part of the badge template configuration is the requirements specification. At least one requirement must be associated with a badge template. -Go to the first badge template details page (admin/badges/credly_badge_templates or admin/badges/accrediblegroup) and add requirements for it: +Go to the first badge template details page (``admin/badges/credlybadgetemplate/`` or ``admin/badges/accrediblegroup/``) and add requirements for it: -1. find the “Badge Requirements” section; +1. find the "Badge Requirements" section; 2. add a new item and select an event type (what is expected to happen); - a. optionally, put a description; + + a. optionally, put a description; + 3. save and navigate to the Requirement details (Change link); - a. optionally, specify data rules in the “Data Rules” section (how exactly it is expected to happen); + + a. optionally, specify data rules in the "Data Rules" section (how exactly it is expected to happen); + 4. add a new item and describe the rule; 5. select a key path - specific data element; 6. select an operator - how to compare the value; -7. enter a value - expected parameter’s value. +7. enter a value - expected parameter's value. .. note:: A configuration for the badge template that must be issued on a specific course completion looks as following: - + - Requirement 1: - event type: ``org.openedx.learning.course.passing.status.updated.v1`` - description: ``On the Demo course completion.`` @@ -124,60 +130,13 @@ Go to the first badge template details page (admin/badges/credly_badge_templates - operator: ``equals`` - value: ``true`` -It is possible to put more than one requirement in a badge template. - -5. Activate configured badge templates --------------------------------------- +A badge template can have more than one requirement. - To activate a badge template check the ``is active`` checkbox on its edit page. +Activate configured badge templates +------------------------------------ -Once badge requirements are set up, it should be “enabled” to start “working”. - -Once enabled, the badge template will be active and ready. +To activate a badge template, check the ``is active`` checkbox on its edit page. .. warning:: - Configuration updates for active badge templates are discouraged since they may cause learners’ inconsistent experience. - -6. See users Badge Progress ---------------------------- - -Current badge progress can be seen in the “Badge progress records” section in the Credentials admin panel. - -Since badge templates can have more than one requirement, there can be partially completed badges. - -7. See awarded user credentials -------------------------------- - -Already earned badges are listed in the "Credly badges" or "Accredible badges" section of the admin panel. - -.. note:: - - This badge is an extended version of a user credential record. - -Once badge progress is complete (all requirements were *fulfilled*), the system: - -1. creates internal user credentials (CredlyBadge or AccredibleBadge); -2. notifies about the badge awarding (public signal); -3. requests Credly or Accredible service to issue the badge (API request). - -8. See issued badges ---------------------------- - -Earned internal badges (user credentials) spread to the badge service. - -On a successful badge issuing, the CredlyBadge or AccredibleBadge user credential is updated with its requisites: - -1. external UUID; -2. external state; - -The Credly badge is visible in the Credly service. -The Accredible badge is visible in the Accredible service. - - -9. Badge template withdrawal ----------------------------- - -Badge template can be deactivated by putting it in the inactive state (``is active`` checkbox). - -Inactive badge templates are ignored during the processing. + Configuration updates for active badge templates are discouraged since they may cause inconsistent learner experience. diff --git a/docs/sharing/badges/settings.rst b/docs/sharing/badges/settings.rst index 66515eb81..cd1ed37c8 100644 --- a/docs/sharing/badges/settings.rst +++ b/docs/sharing/badges/settings.rst @@ -1,200 +1,237 @@ +.. _badges-settings: + Badging Settings ================= -.. note:: - - You can find technical details on how to set up proper configurations for badges to be active in this section. +These settings control the Badges feature: availability, event subscriptions, and provider integration (Credly, Accredible). -Badges feature settings allow configuration: +.. tip:: -1. feature availability; -2. event bus public signals subset for badges; -3. the Credly service integration details (URLs, sandbox usage, etc.); -4. the Accredible service integration details (URLs, sandbox usage, etc.); + The `tutor-contrib-badges`_ plugin configures all required settings automatically. The reference below is for manual or customized deployments. -You can use tutor plugin to setup all needed configurations: +.. _tutor-contrib-badges: https://github.com/raccoongang/tutor-contrib-badges -https://github.com/raccoongang/tutor-contrib-badges - -Feature switch +Feature Switch -------------- -The Badges feature is under a feature switch (disabled by default). - -To enable the feature, update these settings as follows: +The Badges feature is disabled by default. Enable it in both services. .. code-block:: python - # Platform services settings: - FEATURES["BADGES_ENABLED"] = True + # Platform (LMS) settings: + FEATURES["BADGES_ENABLED"] = True - # Credentials service settings: - BADGES_ENABLED = True + # Credentials service settings: + BADGES_ENABLED = True -Default settings ----------------- +``BADGES_CONFIG`` Reference +---------------------------- -The feature has its configuration: +``BADGES_CONFIG`` is the main configuration dictionary for the Credentials service. Below are the defaults - override only what you need. .. code-block:: python - # Credentials settings: - BADGES_CONFIG = { - # these events become available in requirements/penalties setup: - "events": [ - "org.openedx.learning.course.passing.status.updated.v1", - "org.openedx.learning.ccx.course.passing.status.updated.v1", - ], - # Credly integration: - "credly": { - "CREDLY_BASE_URL": "https://credly.com/", - "CREDLY_API_BASE_URL": "https://api.credly.com/v1/", - "CREDLY_SANDBOX_BASE_URL": "https://sandbox.credly.com/", - "CREDLY_SANDBOX_API_BASE_URL": "https://sandbox-api.credly.com/v1/", - "USE_SANDBOX": False, - }, - # Accredible integration: - "accredible": { - "ACCREDIBLE_BASE_URL": "https://dashboard.accredible.com/", - "ACCREDIBLE_API_BASE_URL": "https://api.accredible.com/v1/", - "ACCREDIBLE_SANDBOX_BASE_URL": "https://sandbox.dashboard.accredible.com/", - "ACCREDIBLE_SANDBOX_API_BASE_URL": "https://sandbox.api.accredible.com/v1/", - "USE_SANDBOX": False, - }, - - # requirements data rules: - "rules": { - "ignored_keypaths": [ - "user.id", - "user.is_active", - "user.pii.username", - "user.pii.email", - "user.pii.name", - ], - }, - } - -- ``events`` - explicit event bus signals list (only events with PII user data in payload are applicable). -- ``credly`` - Credly integration details. -- ``accredible`` - Accredible integration details. -- ``rules.ignored_keypaths`` - event payload paths to exclude from data rule options (see: Configuration_). - -Credly integration -~~~~~~~~~~~~~~~~~~ - -- USE_SANDBOX - enables Credly sandbox usage (development, testing); -- CREDLY_BASE_URL - Credly service host URL; -- CREDLY_API_BASE_URL - Credly API host URL; -- CREDLY_SANDBOX_BASE_URL - Credly sandbox host URL; -- CREDLY_SANDBOX_API_BASE_URL - Credly sandbox API host URL; - -Accredible integration -~~~~~~~~~~~~~~~~~~~~~~ -- USE_SANDBOX - enables Accredible sandbox usage (development, testing); -- ACCREDIBLE_BASE_URL - Accredible service host URL; -- ACCREDIBLE_API_BASE_URL - Accredible API host URL; -- ACCREDIBLE_SANDBOX_BASE_URL - Accredible sandbox host URL; - -Event bus settings ------------------- - - ``learning-badges-lifecycle`` is the event bus topic for all Badges related events. - -The Badges feature has updated event bus producer configurations for the Platform and the Credentials services. - -Source public signals -~~~~~~~~~~~~~~~~~~~~~ - -Platform's event bus producer configuration was extended with 2 public signals: - -1. information about the fact someone’s course grade was updated (allows course completion recognition); -2. information about the fact someone’s CCX course grade was updated (allows CCX course completion recognition). - -.. code-block:: python - - # Platform services settings: - EVENT_BUS_PRODUCER_CONFIG = { - ... - - "org.openedx.learning.course.passing.status.updated.v1": { - "learning-badges-lifecycle": { - "event_key_field": "course_passing_status.course.course_key", - "enabled": _should_send_learning_badge_events, - }, - }, - "org.openedx.learning.ccx.course.passing.status.updated.v1": { - "learning-badges-lifecycle": { - "event_key_field": "course_passing_status.course.course_key", - "enabled": _should_send_learning_badge_events, - }, - }, - } + BADGES_CONFIG = { + "events": [ + "org.openedx.learning.course.passing.status.updated.v1", + "org.openedx.learning.ccx.course.passing.status.updated.v1", + ], + "credly": { + "CREDLY_BASE_URL": "https://credly.com/", + "CREDLY_API_BASE_URL": "https://api.credly.com/v1/", + "CREDLY_SANDBOX_BASE_URL": "https://sandbox.credly.com/", + "CREDLY_SANDBOX_API_BASE_URL": "https://sandbox-api.credly.com/v1/", + "USE_SANDBOX": False, + }, + "accredible": { + "ACCREDIBLE_BASE_URL": "https://dashboard.accredible.com/", + "ACCREDIBLE_API_BASE_URL": "https://api.accredible.com/v1/", + "ACCREDIBLE_SANDBOX_BASE_URL": "https://sandbox.dashboard.accredible.com/", + "ACCREDIBLE_SANDBOX_API_BASE_URL": "https://sandbox.api.accredible.com/v1/", + "USE_SANDBOX": False, + }, + "rules": { + "ignored_keypaths": [ + "user.id", + "user.is_active", + "user.pii.username", + "user.pii.email", + "user.pii.name", + "course.display_name", + "course.start", + "course.end", + ], + }, + } + +Top-level keys +~~~~~~~~~~~~~~ + +.. list-table:: + :header-rows: 1 + :widths: 25 75 + + * - Key + - Description + * - ``events`` + - Event bus signals available for requirements and penalties. Only events whose payload includes learner PII (``UserData``) are applicable. + * - ``credly`` + - Credly provider URLs and sandbox toggle (see below). + * - ``accredible`` + - Accredible provider URLs and sandbox toggle (see below). + * - ``rules.ignored_keypaths`` + - Event payload paths excluded from data rule options in the admin UI (see :ref:`badges-configuration`). + +Credly Settings +~~~~~~~~~~~~~~~ + +.. list-table:: + :header-rows: 1 + :widths: 35 65 + + * - Setting + - Description + * - ``USE_SANDBOX`` + - Use Credly sandbox environment for development and testing. + * - ``CREDLY_BASE_URL`` + - Credly production host URL. + * - ``CREDLY_API_BASE_URL`` + - Credly production API URL. + * - ``CREDLY_SANDBOX_BASE_URL`` + - Credly sandbox host URL. + * - ``CREDLY_SANDBOX_API_BASE_URL`` + - Credly sandbox API URL. + +Accredible Settings +~~~~~~~~~~~~~~~~~~~ + +.. list-table:: + :header-rows: 1 + :widths: 35 65 + + * - Setting + - Description + * - ``USE_SANDBOX`` + - Use Accredible sandbox environment for development and testing. + * - ``ACCREDIBLE_BASE_URL`` + - Accredible production host URL. + * - ``ACCREDIBLE_API_BASE_URL`` + - Accredible production API URL. + * - ``ACCREDIBLE_SANDBOX_BASE_URL`` + - Accredible sandbox host URL. + * - ``ACCREDIBLE_SANDBOX_API_BASE_URL`` + - Accredible sandbox API URL. + + +Event Bus Configuration +----------------------- -Emitted public signals -~~~~~~~~~~~~~~~~~~~~~~ - -The Badges feature introduced 2 own event types: +.. note:: -1. information about the fact someone has earned a badge; -2. information about the fact someone's badge was revoked; + If you use the `tutor-contrib-badges`_ plugin, event bus configuration is handled automatically. This section is for custom deployments. -.. code-block:: python +All badge-related events use the ``learning-badges-lifecycle`` topic. - # Credentials service settings: - EVENT_BUS_PRODUCER_CONFIG = { - ... +Source Signals (Platform) +~~~~~~~~~~~~~~~~~~~~~~~~~ - "org.openedx.learning.badge.awarded.v1": { - "learning-badges-lifecycle": {"event_key_field": "badge.uuid", "enabled": True }, - }, - "org.openedx.learning.badge.revoked.v1": { - "learning-badges-lifecycle": {"event_key_field": "badge.uuid", "enabled": True }, - }, - } +The Platform (LMS) produces two signals that trigger badge processing. -Consuming workers -~~~~~~~~~~~~~~~~~ +.. list-table:: + :header-rows: 1 + :widths: 55 45 -.. note:: + * - Signal + - Purpose + * - ``org.openedx.learning.course.passing.status.updated.v1`` + - Course grade updated - enables course completion recognition. + * - ``org.openedx.learning.ccx.course.passing.status.updated.v1`` + - CCX course grade updated - enables CCX course completion recognition. - Consumers implementation depends on the used event bus. +.. code-block:: python -Event bus options: + # Platform (LMS) settings: + EVENT_BUS_PRODUCER_CONFIG = { + ... + "org.openedx.learning.course.passing.status.updated.v1": { + "learning-badges-lifecycle": { + "event_key_field": "course_passing_status.course.course_key", + "enabled": _should_send_learning_badge_events, + }, + }, + "org.openedx.learning.ccx.course.passing.status.updated.v1": { + "learning-badges-lifecycle": { + "event_key_field": "course_passing_status.course.course_key", + "enabled": _should_send_learning_badge_events, + }, + }, + } + +Emitted Signals (Credentials) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The Credentials service emits two signals after badge processing completes. + +.. list-table:: + :header-rows: 1 + :widths: 55 45 + + * - Signal + - Purpose + * - ``org.openedx.learning.badge.awarded.v1`` + - A badge was awarded to a learner. + * - ``org.openedx.learning.badge.revoked.v1`` + - A badge was revoked from a learner. -- Redis Streams -- Kafka -- ... +.. code-block:: python -The Credentials and the Platform services **produce** (push) their public signals as messages to the stream. + # Credentials service settings: + EVENT_BUS_PRODUCER_CONFIG = { + ... + "org.openedx.learning.badge.awarded.v1": { + "learning-badges-lifecycle": { + "event_key_field": "badge.uuid", + "enabled": BADGES_ENABLED, + }, + }, + "org.openedx.learning.badge.revoked.v1": { + "learning-badges-lifecycle": { + "event_key_field": "badge.uuid", + "enabled": BADGES_ENABLED, + }, + }, + } -To **consume** (pull) those messages a consumer process is required. +These signals are only produced when ``BADGES_ENABLED`` is ``True``. -Redis Streams -############# +Consumer Setup +~~~~~~~~~~~~~~ -When the Redis Streams event bus is used, the ``-learning-badges-lifecycle`` stream is used for messages transport. +The consumer implementation depends on your event bus backend (Redis Streams, Kafka, etc.). -For producing and consuming a single package (broker) is used - event-bus-redis_. +Both the Credentials and Platform services **produce** messages to the event stream. A separate **consumer** process pulls and handles those messages. -"Event Bus Redis" is implemented as a Django application and provides a Django management command for consuming messages -(see all details in the package's README). +**Redis Streams** - uses the event-bus-redis_ package, which provides a Django management command. .. code-block:: bash - # Credentials service consumer example: - /edx/app/credentials/credentials/manage.py consume_events -t learning-badges-lifecycle -g credentials_dev --extra={"consumer_name":"credentials_dev.consumer1"} + # Credentials service consumer (required for badge processing): + ./manage.py consume_events \ + -t learning-badges-lifecycle \ + -g credentials_dev \ + --extra='{"consumer_name": "credentials_dev.consumer1"}' - # LMS service consumer example: - /edx/app/edxapp/edx-platform/manage.py lms consume_events -t learning-badges-lifecycle -g lms_dev --extra={"consumer_name":"lms_dev.consumer1"} - -.. note:: + # LMS consumer (optional - only if LMS needs badge award/revoke notifications): + ./manage.py lms consume_events \ + -t learning-badges-lifecycle \ + -g lms_dev \ + --extra='{"consumer_name": "lms_dev.consumer1"}' - **Credentials event bus consumer** is crucial for the Badges feature, since it is responsible for all incoming events processing. +.. important:: - **LMS event bus consumer** is only required if LMS wants to receive information about badges processing results (awarding/revocation). + The **Credentials consumer** is required - it processes all incoming badge events. The **LMS consumer** is optional and only needed if LMS should react to badge award or revocation signals. -.. _Configuration: configuration.html -.. _event-bus-redis: https://github.com/openedx/event-bus-redis \ No newline at end of file +.. _event-bus-redis: https://github.com/openedx/event-bus-redis diff --git a/docs/sharing/index.rst b/docs/sharing/index.rst index 716c2566b..12472dfa3 100644 --- a/docs/sharing/index.rst +++ b/docs/sharing/index.rst @@ -8,10 +8,10 @@ third-party platforms, professional networks, and digital wallets. This section covers two sharing mechanisms. -- **Badges** — issue digital badges through providers like Credly +- **Badges** - issue digital badges through providers like Credly and Accredible. Badges follow the Open Badges standard and can be displayed on LinkedIn, personal websites, and other platforms. -- **Verifiable Credentials** — issue W3C-compliant verifiable +- **Verifiable Credentials** - issue W3C-compliant verifiable credentials that learners store in digital wallets. These credentials are cryptographically signed and independently verifiable. diff --git a/docs/sharing/verifiable_credentials/components.rst b/docs/sharing/verifiable_credentials/components.rst index 9f4b361e0..0229b0299 100644 --- a/docs/sharing/verifiable_credentials/components.rst +++ b/docs/sharing/verifiable_credentials/components.rst @@ -1,3 +1,5 @@ +.. _vc-components: + Components ========== @@ -5,20 +7,24 @@ The Verifiable Credentials feature includes the following parts: - **Verifiable Credentials application** (`credentials.apps.verifiable_credentials` within the Open edX Credentials IDA); - **Learner Record MFE** (`frontend-app-learner-record` micro-frontend); -- third-party plugins (see `Extensibility`_) -- digital wallets (see `Storages`_) +- third-party plugins (see :ref:`vc-extensibility`) +- digital wallets (see :ref:`vc-storages-page`) + +.. _vc-application: Verifiable Credentials application ---------------------------------- The core backend logic and all related API are encapsulated in the `Verifiable Credentials application`_. -Once the Verifiable Credentials feature `is enabled `__: +Once the Verifiable Credentials feature :ref:`is enabled `: 1. Admin site "Verifiable Credentials" section becomes available in the Credentials IDA. 2. Extra urls become available in the Credentials IDA. 3. Extra API endpoints become available within the Credentials IDA. +.. _vc-administration-site: + Administration site ~~~~~~~~~~~~~~~~~~~ @@ -35,7 +41,8 @@ Currently, only a single Issuer configuration can be active in a moment of time: .. image:: ../../_static/images/verifiable_credentials-issuer-configuration.png :alt: Issuance Configurations -Issuance configuration describes an Issuer - Organization/University/School on behalf of which verifiable credentials are created. Issuer's ID becomes a part of a verifiable credential and a cryptographic proof is generated with the help of Issuer's private key. Each Issuer has a verbose name. It can be deactivated (checkbox). +Issuance configuration describes an Issuer - Organization/University/School on behalf of which verifiable credentials are created. Issuer's ID becomes a part of a verifiable +credential and a cryptographic proof is generated with the help of Issuer's private key. Each Issuer has a verbose name. It can be deactivated (checkbox). .. note:: Private key itself is a secret that is generated with the help of a cryptographic software. @@ -53,7 +60,12 @@ Issuance line has its unique identifier and additionally includes this informati 2. **Issuer ID** - issuer which signs this verifiable credential 3. **Storage ID** - a storage backend (digital wallet) which will keep a verifiable credential 4. **Processing status** - if a verifiable credential was successfully uploaded to storage -5. **Status list info** - indicates if a verifiable credential still valid and unique status index within an Issuer's status list +5. **Status list info** - indicates if a verifiable credential is still valid and unique status index within an Issuer's status list +6. **Subject ID** - verifiable credential subject DID +7. **Data model ID** - verifiable credential specification to use +8. **Expiration date** - optional expiration timestamp for the verifiable credential + +.. _vc-learner-record-mfe: Learner Record Microfrontend ----------------------------- @@ -63,7 +75,7 @@ The Verifiable Credentials feature extends the `Learner Record MFE`_ with additi .. image:: ../../_static/images/verifiable_credentials-learner-record-mfe.png :alt: Verifiable Credentials page -1. Once the Verifiable Credentials feature `is enabled `__ tabs navigation appears +1. Once the Verifiable Credentials feature :ref:`is enabled ` tabs navigation appears 2. All learner's Open edX credentials are listed within the page 3. Achievement card has an action button that allows verifiable credential requesting based on the corresponding Open edX credential 4. Storages options (experimental) @@ -71,14 +83,16 @@ The Verifiable Credentials feature extends the `Learner Record MFE`_ with additi .. note:: Currently, a single (built-in) storage backend is implemented out of the box (`Learner Credential Wallet`_). In this case the only storage option is available by default, so "Create" action button won't have a dropdown. Additional storages appear under the "Create with" dropdown automatically once configured. +.. _vc-status-list-api: + Status List API --------------- -There are plenty of reasons verifiable credential may be already invalid, inactive or disposed: +There are several reasons a verifiable credential may already be invalid, inactive, or disposed: - revocation - implicit expiration -- a lot of other purposes +- other status changes Open edX maintains status for internal credentials ("awarded", "revoked"). @@ -161,14 +175,11 @@ Every verifiable credential carries its status list "registration" info. "statusListIndex": "15" }, -Also see related `management command`_ +Also see related :ref:`management command ` .. _Verifiable Credentials application: https://github.com/openedx/credentials/tree/master/credentials/apps/verifiable_credentials .. _Learner Record MFE: https://github.com/openedx/frontend-app-learner-record -.. _Extensibility: extensibility.html .. _decentralized identifier: https://en.wikipedia.org/wiki/Decentralized_identifier .. _Learner Credential Wallet: https://lcw.app/ .. _Privacy Considerations: https://w3c.github.io/vc-status-list-2021/#privacy-considerations -.. _management command: configuration.html#status-list-helper -.. _storages: storages.html \ No newline at end of file diff --git a/docs/sharing/verifiable_credentials/configuration.rst b/docs/sharing/verifiable_credentials/configuration.rst index 1ca1dbb14..bae4210e2 100644 --- a/docs/sharing/verifiable_credentials/configuration.rst +++ b/docs/sharing/verifiable_credentials/configuration.rst @@ -1,3 +1,5 @@ +.. _vc-configuration: + Configuration ============= @@ -6,19 +8,19 @@ Verifiable Credentials feature is optional. It is disabled by default. Learner Record micro-frontend ----------------------------- -The most of configuration is related to the Credentials IDA (`verifiable_credentials` app), but there are few UI-related settings. +Most configuration is related to the Credentials IDA (``verifiable_credentials`` app), but there are a few UI-related settings. ``ENABLE_VERIFIABLE_CREDENTIALS`` (boolean) - enables feature appearance (extra routes) -``SUPPORT_URL_VERIFIABLE_CREDENTIALS`` (URL string) - footer support link +``SUPPORT_URL_VERIFIABLE_CREDENTIALS`` (URL string) - footer support link. Note: this setting belongs to the Learner Record MFE (frontend-app-learner-record), not the Credentials IDA. + +The feature introduces its own set of default settings which are namespaced in the VERIFIABLE_CREDENTIALS setting, like this: Verifiable Credentials application ---------------------------------- ``ENABLE_VERIFIABLE_CREDENTIALS`` (boolean) - main feature flag -The feature introduces its own set of default settings which are namespaced in the VERIFIABLE_CREDENTIALS setting, like this: - .. code-block:: python VERIFIABLE_CREDENTIALS = { @@ -71,7 +73,7 @@ There is a set of built-in predefined settings: Default data models ------------------- -Deployment configuration can override `data models set`_ with the respect of the following restrictions: +Deployment configuration can override the :ref:`data models set ` with respect to the following restrictions: - there always must be at least 1 data model available - each storage is pre-configured to use some data model which must be available @@ -79,7 +81,7 @@ Deployment configuration can override `data models set`_ with the respect of the Default storages ---------------- -Deployment configuration can override `storages set`_ with the respect of the following restrictions: +Deployment configuration can override the :ref:`storages set ` with respect to the following restrictions: - there always must be at least 1 storage available @@ -88,9 +90,9 @@ Default issuer -------------- .. note:: - Currently, there is only a single active issuer (system-wide) available So, all verifiable credentials are created (issued) on behalf of this Issuer. + Currently, there is only a single active issuer (system-wide) available. All verifiable credentials are created (issued) on behalf of this Issuer. -There is the `Issuance Configuration`_ database model, which initial record is created based on these settings. +There is the :ref:`Issuance Configuration ` database model, which initial record is created based on these settings. NAME ~~~~ @@ -138,19 +140,23 @@ Other settings are available for advanced tweaks but usually are not meant to be - Default issuance request serializer (incoming issuance request parsing) - Default renderer (outgoing verifiable credential presentation) +.. _vc-management-commands: + Management commands ------------------- There are a couple of service commands available for the verifiable_credentials application. +.. _vc-issuer-credentials-helper: + Issuer credentials helper ~~~~~~~~~~~~~~~~~~~~~~~~~ -**Generates private key for Issuer (JWK) and a decentralized identifier (DID) based on that key.** +**Generates a new private key for Issuer (JWK) and a decentralized identifier (DID) based on that key.** .. code-block:: sh - root@credentials:/edx/app/credentials/credentials# ./manage.py generate_issuer_credentials + ./manage.py generate_issuer_credentials >> {'did': 'did:key:z6MkgdiV7pVPCapM8oUwfhxBwYZgh8dXkHkJykSAc4DHKD7X', 'private_key': '{"kty":"OKP","crv":"Ed25519","x":"IGUT8E_aRNzLqouWO4zdeZ6l4CEXsVmJDOpOQS69m7o","d":"vn8xgdO5Ki3zlvRNc2nUqcj50Ise1Vl1tlbs9DUL-hg"}'} @@ -163,16 +169,19 @@ Issuer configuration helpers root@credentials:/edx/app/credentials/credentials# ./manage.py create_default_issuer -Initial Issuance configuration is created based on VERIFIABLE_CREDENTIALS[DEFAULT_ISSUER] via data migration during the first deployment. This helper allows repeating the process manually if needed (Additional configurations can be created from django admin interface). +Initial Issuance configuration is created based on VERIFIABLE_CREDENTIALS[DEFAULT_ISSUER] via data migration during the first deployment. This helper allows repeating the process +manually if needed (Additional configurations can be created from django admin interface). **Remove Issuance Configuration based on Issuer ID.** .. code-block:: sh - root@credentials:/edx/app/credentials/credentials# ./manage.py remove_issuance_configuration did:key:z6MkgdiV7pVPCapM8oUwfhxBwYZgh8dXkHkJykSAc4DHKD7X + ./manage.py remove_issuance_configuration did:key: Issuance configuration delete operation is forbidden in admin interface (only deactivation is available). This tool allows to cleanup configurations list if needed. +.. _vc-status-list-helper: + Status List helper ~~~~~~~~~~~~~~~~~~ @@ -180,13 +189,10 @@ Status List helper .. code-block:: sh - root@credentials:/edx/app/credentials/credentials# ./manage.py generate_status_list did:key:z6MkgdiV7pVPCapM8oUwfhxBwYZgh8dXkHkJykSAc4DHKD7X + ./manage.py generate_status_list did:key: Allows Status List verifiable credential generation (for a given Issuer ID). -.. _data models set: extensibility.html#data-models -.. _storages set: extensibility.html#storages .. _didkit: https://pypi.org/project/didkit/ .. _example: https://github.com/spruceid/didkit-python/blob/main/examples/python_django/didkit_django/issue_credential.py#L12 .. _related specs : https://w3c.github.io/vc-status-list-2021/#revocation-bitstring-length -.. _Issuance Configuration: components.html#administration-site \ No newline at end of file diff --git a/docs/sharing/verifiable_credentials/extensibility.rst b/docs/sharing/verifiable_credentials/extensibility.rst index e99e1a0c8..0501a3348 100644 --- a/docs/sharing/verifiable_credentials/extensibility.rst +++ b/docs/sharing/verifiable_credentials/extensibility.rst @@ -1,12 +1,18 @@ +.. _vc-extensibility: + Extensibility ============= +.. _vc-storages: + Storages -------- Storage backend classes describe a destination for issued verifiable credentials. Basically, storages are wallets (mobile or web applications). -See available options on `Storages page`_. +See available options on the :ref:`Storages page `. + +.. _vc-data-models: Data Models ----------- @@ -16,12 +22,13 @@ Data model classes are `DRF`_ serializers which compose verifiable credentials o Credentials data models ~~~~~~~~~~~~~~~~~~~~~~~ -There are 2 specifications included by default: +There are 3 specifications included by default: - `Open Badges Specification v3.0`_ (see `OB3.0 model`_) +- `Open Badges Specification v3.0.1`_ (see `OB3.0.1 model`_) - `Verifiable Credentials Data Model v1.1`_ (see `VC1.1 model`_) - experimental -Additional specifications may be implemented as separate `plugins`_. +Additional specifications may be implemented as separate :ref:`plugins `. Credentials status information ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -30,7 +37,8 @@ Credentials status information Status information allows instant checks to figure out if the presented verifiable credential is still valid. The credential issuer can invalidate a verifiable credential by updating its indexed record in the status list. -`Status List v2021`_ is a special kind of verifiable credential. It serves as a mechanism of verification for issued verifiable credentials (meaning, it does not carry achievement information itself but it is a registry of statuses for all created achievement-related verifiable credentials). +:ref:`Status List v2021 ` is a special kind of verifiable credential. It serves as a mechanism of verification for issued verifiable credentials (meaning, it does not carry achievement information +itself but it is a registry of statuses for all created achievement-related verifiable credentials). - `Verifiable Credential Status List v2021`_ @@ -39,10 +47,12 @@ There are 2 parts of the approach: - status entry (becomes a part of each issued verifiable credential and carries the info "how to check status") - status list (an Issuer-centric separate freely reachable statuses registry) +.. _vc-plugins: + Plugins ------- -Both `data models`_ and `storages`_ may be implemented as Credentials IDA installable pluggable applications. +Both :ref:`data models ` and :ref:`storages ` may be implemented as Credentials IDA installable pluggable applications. .. note:: @@ -50,15 +60,12 @@ Both `data models`_ and `storages`_ may be implemented as Credentials IDA instal .. _Verifiable Credentials Data Model v1.1: https://www.w3.org/TR/vc-data-model-1.1/ .. _Open Badges Specification v3.0: https://1edtech.github.io/openbadges-specification/ob_v3p0.html +.. _Open Badges Specification v3.0.1: https://www.imsglobal.org/spec/ob/v3p0/impl/ .. _Verifiable Credential Status List v2021: https://w3c.github.io/vc-status-list-2021/ -.. _data models: extensibility.html#data-models -.. _storages: extensibility.html#storages -.. _storages page: storages.html -.. _plugins: extensibility.html#plugins .. _Raccoon Gang : https://raccoongang.com .. _Learner Credential Wallet: https://lcw.app .. _DRF: https://www.django-rest-framework.org/ -.. _Status List v2021: components.html#status-list-api .. _VC1.1 model: https://github.com/openedx/credentials/blob/master/credentials/apps/verifiable_credentials/composition/verifiable_credentials.py .. _OB3.0 model: https://github.com/openedx/credentials/blob/master/credentials/apps/verifiable_credentials/composition/open_badges.py -.. _openedx-wallet: https://github.com/raccoongang/openedx-wallet \ No newline at end of file +.. _OB3.0.1 model: https://github.com/openedx/credentials/blob/master/credentials/apps/verifiable_credentials/composition/open_badges.py +.. _openedx-wallet: https://github.com/raccoongang/openedx-wallet diff --git a/docs/sharing/verifiable_credentials/overview.rst b/docs/sharing/verifiable_credentials/overview.rst index d839b92f3..fb0817ac7 100644 --- a/docs/sharing/verifiable_credentials/overview.rst +++ b/docs/sharing/verifiable_credentials/overview.rst @@ -1,14 +1,62 @@ Verifiable Credentials ====================== -An optional feature that allows issuance of the `Verifiable Credentials`_ based on the Open edX achievements. +Traditional certificates (PDFs, images) are easy to forge and hard to verify. +Employers and institutions that receive them must contact the issuing organization +to confirm authenticity - a slow, manual process that doesn't scale. - *Verifiable credentials will allow us to represent our achievements in a provable, portable, sharable, privacy and autonomy preserving way.* +`Verifiable Credentials`_ (VCs) solve this problem. A VC is a digitally signed, +tamper-proof data object that any party can verify instantly, without contacting +the issuer. The `W3C Verifiable Credentials Data Model`_ and related +specifications define the standard. -Please, see `Extensibility`_ section for the list of supported: +Who Benefits +------------ -- verifiable credential specifications (data models) -- digital wallets (storages) +- **Learners** receive portable, privacy-preserving proof of their achievements. + They store VCs in a digital wallet and share them with anyone - employers, + other institutions, professional networks - on their own terms. +- **Operators** (institutions, universities) issue VCs from their Open edX + platform. The cryptographic signature ties each credential back to the issuer, + strengthening the institution's brand and trust. +- **Relying parties** (employers, admissions offices) verify a credential in + seconds. No phone calls, no email chains - just a standard verification check + against a public :ref:`Status List `. + +How It Works in Open edX +------------------------ + +The Verifiable Credentials feature is optional. Once enabled, it extends the +Credentials service and Learner Record micro-frontend. + +The typical flow looks like this. + +#. A learner earns an Open edX credential (course or program certificate). +#. The learner visits the Learner Record page and requests a verifiable + credential. +#. The platform signs the credential using the configured issuer's private key + and uploads it to the learner's digital wallet. +#. The learner can now present the VC to any relying party. +#. The relying party verifies the signature and checks the issuer's public + status list to confirm the credential is still valid (not expired or + revoked). + +Operator Experience +------------------- + +Setting up VCs involves a few steps. + +#. Enable the feature flag (``ENABLE_VERIFIABLE_CREDENTIALS``). +#. Generate issuer credentials (a decentralized identifier and private key). +#. Configure the issuer in the Credentials admin site. +#. Ensure the Status List API endpoint is publicly accessible. + +See the :ref:`Quick Start ` guide for detailed instructions. + +The feature supports multiple verifiable credential specifications +(Open Badges v3.0, v3.0.1, and the W3C VC Data Model v1.1) and multiple +digital wallet backends. Both can be extended through plugins - see +:ref:`vc-extensibility` for details. ---- @@ -24,4 +72,4 @@ Please, see `Extensibility`_ section for the list of supported: tech_details .. _Verifiable Credentials: https://en.wikipedia.org/wiki/Verifiable_credentials -.. _Extensibility: extensibility.html \ No newline at end of file +.. _W3C Verifiable Credentials Data Model: https://www.w3.org/TR/vc-data-model-1.1/ diff --git a/docs/sharing/verifiable_credentials/quickstart.rst b/docs/sharing/verifiable_credentials/quickstart.rst index 98dc90c74..4dc4b1685 100644 --- a/docs/sharing/verifiable_credentials/quickstart.rst +++ b/docs/sharing/verifiable_credentials/quickstart.rst @@ -1,3 +1,5 @@ +.. _vc-quickstart: + Quick Start =================================== @@ -17,12 +19,12 @@ Since Verifiable Credentials feature is optional, it must be enabled to be acces # both Credentials service and Learner Record MFE: ENABLE_VERIFIABLE_CREDENTIALS = true -See Configuration_ for more details. +See :ref:`vc-configuration` for more details. 2. Issuer credentials generation -------------------------------- -Once enabled Verifiable Credentials feature has reasonable defaults. The only additional activity is needed - issuer_ credentials setup. Unless we already have appropriate issuer key and issuer ID, we have to generate those: +Once enabled, the Verifiable Credentials feature has reasonable defaults. The only additional step needed is the issuer_ credentials setup. Unless you already have an appropriate issuer key and issuer ID, you need to generate them: .. code:: @@ -38,14 +40,14 @@ Here: - "did" - unique Issuer decentralized identifier - "private_key" - Issuer private JWK -See `Management commands`_ for more details. +See :ref:`vc-management-commands` for more details. 3. Issuer credentials setup --------------------------- Use the generated credentials to replace the stub values in the auto-created Issuance Configuration. -Enter Credentials Administration interface and find "VERIFIABLE CREDENTIALS" section (`/admin/verifiable_credentials/issuanceconfiguration/`). +Enter Credentials Administration interface and find "VERIFIABLE CREDENTIALS" section (``/admin/verifiable_credentials/issuanceconfiguration/``). .. code:: @@ -58,7 +60,7 @@ Enter Credentials Administration interface and find "VERIFIABLE CREDENTIALS" sec Make sure the configuration is enabled. -See `Administration site`_ for more details. +See :ref:`vc-administration-site` for more details. 4. Ensure status list is accessible ----------------------------------- @@ -70,18 +72,13 @@ Status List API endpoint is crucial for the feature. Once everything is configur # each Issuer maintains its own Status List: https://credentials.example.com/verifiable_credentials/api/v1/status-list/2021/v1// -See `Status List API`_ for more details. +See :ref:`vc-status-list-api` for more details. 5. Issuer registration (Learner Credential Wallet) -------------------------------------------------- This step is specific for the Learner Credential Wallet storage. -See Learner Credential Wallet `usage prerequisites`_. +See Learner Credential Wallet :ref:`usage prerequisites `. .. _issuer: https://www.w3.org/TR/vc-data-model-1.1/#dfn-issuers -.. _configuration: configuration.html#configuration -.. _management commands: configuration.html#management-commands -.. _administration site: components.html#administration-site -.. _status list API: components.html#status-list-api -.. _usage prerequisites: storages.html#usage-prerequisites \ No newline at end of file diff --git a/docs/sharing/verifiable_credentials/storages.rst b/docs/sharing/verifiable_credentials/storages.rst index 58ae45856..1be9e65ae 100644 --- a/docs/sharing/verifiable_credentials/storages.rst +++ b/docs/sharing/verifiable_credentials/storages.rst @@ -1,3 +1,5 @@ +.. _vc-storages-page: + Storages ======== @@ -12,6 +14,8 @@ Learner Credential Wallet Learner Credential Wallet (LCWallet) is a mobile app available for Android and IOS devices. +.. _vc-usage-prerequisites: + Usage prerequisites ~~~~~~~~~~~~~~~~~~~ @@ -40,7 +44,7 @@ This explains a generic usage flow for learners. :alt: Learner Credential Wallet setup step 3 :width: 30% -#. Learners navigate Learner Record MFE interface (`Verifiable Credentials tab`_) and claim for a verifiable credential issuance (clicking a :guilabel:`Create` button). +#. Learners navigate Learner Record MFE interface (:ref:`Verifiable Credentials tab `) and claim for a verifiable credential issuance (clicking a :guilabel:`Create` button). #. On the next step learners are asked for QR code scanning - that's where the LCWallet app starts its flow. Learners use :guilabel:`Scan QR code` option in the mobile application. @@ -151,5 +155,4 @@ Additionally, you can install the `openedx-wallet`_ POC for investigation/onboar .. _Digital Credentials Consortium: https://digitalcredentials.mit.edu/ .. _community issuer registry: https://github.com/digitalcredentials/community-registry .. _`Sandbox Registry`: https://github.com/digitalcredentials/sandbox-registry -.. _`Verifiable Credentials tab`: components.html#learner-record-microfrontend -.. _openedx-wallet: https://github.com/raccoongang/openedx-wallet \ No newline at end of file +.. _openedx-wallet: https://github.com/raccoongang/openedx-wallet diff --git a/docs/sharing/verifiable_credentials/tech_details.rst b/docs/sharing/verifiable_credentials/tech_details.rst index 06d4709c2..87186d92c 100644 --- a/docs/sharing/verifiable_credentials/tech_details.rst +++ b/docs/sharing/verifiable_credentials/tech_details.rst @@ -9,7 +9,8 @@ Prerequisites Required initial activities. 1. Before the main feature flag (settings) is enabled the verifiable_credentials app won't register its urlconf, admin. -2. Default built-in configuration is almost self-contained - the only required step is to configure Issuer's credentials (see `management command helper`_). If Issuer is configured in deployment environment from the start, those settings are used during the app data migration, otherwise manual Issuance Configuration edit is needed (Credentials admin site). +2. Default built-in configuration is almost self-contained - the only required step is to configure Issuer's credentials (see :ref:`management command helper `). If Issuer is configured in + deployment environment from the start, those settings are used during the app data migration, otherwise manual Issuance Configuration edit is needed (Credentials admin site). 3. There can be a list of Issuance Configuration records, but only the last enabled is taken into account in current implementation. Events flow @@ -23,11 +24,11 @@ Here is how everything happens. - 1 - Learner navigates to the Learner Record MFE, enters the Verifiable Credentials page. - 2,3 - Frontend fetches all Learner's credentials (program certificates). - 4,5 - Frontend fetches configured storages list. -- Learner chooses theirs credential (program certificate) to issue verifiable credential for. +- Learner chooses their credential (program certificate) to issue verifiable credential for. - 6,7 - Learner initiates an issuance (standard case: single storage, experimental case: many storages). - 8 - Issuance Line is created with given context (storage + program certificate). - 9 - all pre-requisites are evaluated and deep-link/QR-code generated. -- Learner is present modal dialog with deep-link/QR-code to proceed with a mobile wallet app. +- Learner sees a modal dialog with deep-link/QR-code to proceed with a mobile wallet app. - 10,11 - Learner interacts with a dialog data (clicks/scans). - 12 - Learner navigates to a mobile wallet app. - 13 - mobile wallet app requests verifiable credential from an issuance API endpoint (on behalf of a Learner). @@ -43,15 +44,14 @@ Verifiable Credentials feature has introduced a couple of extra packages. didkit-python ~~~~~~~~~~~~~ -``didkit==0.3.2`` +``didkit==0.3.3`` A tool for verifiable credentials operations (issuance, verification, signing, validation). qrcode ~~~~~~ -``qrcode==7.4.2`` +``qrcode==8.2`` We generate mobile deep-link QR-codes on a backend. -.. _management command helper: configuration.html#issuer-credentials-helper diff --git a/docs/sharing/verifiable_credentials/usage.rst b/docs/sharing/verifiable_credentials/usage.rst index bc194262c..c8c53b33f 100644 --- a/docs/sharing/verifiable_credentials/usage.rst +++ b/docs/sharing/verifiable_credentials/usage.rst @@ -4,7 +4,7 @@ Usage The Open edX platform allows students to earn credentials (e.g. course certificates, program certificates). Based on such credentials learners are able to create a digital cryptographically proven piece of data - a verifiable credential. .. note:: - Verifiable credentials are intended for machines. + Verifiable credentials are machine-verifiable, meaning they can be automatically validated by software without human intervention. A single Open edX achievement can be used as a source for numerous verifiable credentials (identical or different data models). @@ -40,7 +40,7 @@ The general usage flow is the following: - **Interested Party verifies** a verifiable credential's status - checks if it wasn't tampered in any way; checks if it still has valid status (not expired, not revoked); .. note:: - Please, see the `Learner Record micro-frontend`_ for details. + Please, see the :ref:`Learner Record micro-frontend ` for details. Administrators -------------- @@ -48,14 +48,11 @@ Administrators The Open edX users with administrator rights are able to manage/monitor the Verifiable Credentials application within the Credentials IDA admin site. .. note:: - Please, see the `Verifiable Credentials application`_ for details. + Please, see the :ref:`Verifiable Credentials application ` for details. Relying Parties --------------- -Third-parties whom a verifiable credential is presented want to ensure the current status of such artifact. That's where the `Status List`_ mechanism comes into play. +Third parties to whom a verifiable credential is presented want to ensure the current status of such artifact. That's where the :ref:`Status List ` mechanism comes into play. -.. _Learner Record micro-frontend: components.html#learner-record-microfrontend -.. _Verifiable Credentials application: components.html#verifiable-credentials-application -.. _Status List: components.html#status-list-api \ No newline at end of file