|
| 1 | +Accredible Configuration |
| 2 | +======================== |
| 3 | + |
| 4 | +.. note:: |
| 5 | + |
| 6 | + This section provides information on how and where to set up accredible badge groups and configuration. |
| 7 | + |
| 8 | +The Badges feature is configured in the Credentials admin panel. |
| 9 | + |
| 10 | +.. image:: ../../_static/images/badges/badges-admin.png |
| 11 | + :alt: Badges administration |
| 12 | + |
| 13 | +Accredible API Configurations |
| 14 | +----------------------------- |
| 15 | + |
| 16 | +Multiple Accredible API Configurations can be configured. |
| 17 | + |
| 18 | +**All communication between Open edX Credentials and Accredible service happens on behalf of a Accredible API config.** |
| 19 | + |
| 20 | +Go to the Accredible API Configs section in the admin panel and create a new item: |
| 21 | + |
| 22 | +1. to set the name for config; |
| 23 | +2. to set the api key, used to sync the Accredible account. |
| 24 | + |
| 25 | +In case of errors, check the credentials used for the API Config |
| 26 | + |
| 27 | +Groups |
| 28 | +--------------- |
| 29 | + |
| 30 | +*Accredible groups* (badge templates for short) are created in the Accredible dashboard and then, they are retrieved by the Credentials via API. |
| 31 | + |
| 32 | +Synchronization |
| 33 | +~~~~~~~~~~~~~~~ |
| 34 | + |
| 35 | +To synchronize Accredible groups for the API Configuration one should: |
| 36 | + |
| 37 | +- navigate "Accredible API Configs" list page; |
| 38 | +- select the API Config; |
| 39 | +- use ``Sync groups`` action; |
| 40 | + |
| 41 | +.. image:: ../../_static/images/badges/badges-admin-groups-sync.png |
| 42 | + :alt: Accredible groups synchronization |
| 43 | + |
| 44 | +On success, the system will update the list of Accredible groups: |
| 45 | + |
| 46 | +- Accredible group records are created inactive (disabled); |
| 47 | + |
| 48 | +For a group to be considered during the processing it must be configured (to have at least 1 requirement) and activated (enabled) first. |
| 49 | + |
| 50 | +Badge Requirements |
| 51 | +------------------ |
| 52 | + |
| 53 | + Requirements describe **what** and **how** must happen on the system to earn a badge. |
| 54 | + |
| 55 | +Badge Requirement(s) specification is a crucial part of group configuration. |
| 56 | +At least one badge requirement must be associated with a group. |
| 57 | + |
| 58 | +Badge Requirements are listed inline on a group detail page. |
| 59 | + |
| 60 | +.. image:: ../../_static/images/badges/badges-admin-template-requirements.png |
| 61 | + :alt: Credly badge template requirements |
| 62 | + |
| 63 | +A badge template can have multiple requirements. All badge requirements must be *fulfilled* before the system will issue a badge to a learner. |
| 64 | + |
| 65 | +Event type |
| 66 | +~~~~~~~~~~ |
| 67 | + |
| 68 | + Describes **what is expected to happen**. |
| 69 | + |
| 70 | +Available event type subset is pre-configured in the application settings. |
| 71 | + |
| 72 | +.. note:: |
| 73 | + |
| 74 | + 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. |
| 75 | + |
| 76 | +Rules |
| 77 | +~~~~~ |
| 78 | + |
| 79 | +A list of configured data rules (if any), see "Data Rules". |
| 80 | + |
| 81 | +Description |
| 82 | +~~~~~~~~~~~ |
| 83 | + |
| 84 | +**Description** is an optional human-readable reminder that describes what the requirement is about. |
| 85 | + |
| 86 | + Badge Requirement can be **deeper specified** via its Data Rules. |
| 87 | + |
| 88 | +Group |
| 89 | +~~~~~ |
| 90 | + |
| 91 | +Optional configuration (by default each badge requirement is assigned a separate Group). |
| 92 | + |
| 93 | +Allows putting 2 or more badge requirements as a Group. |
| 94 | +Requirements group is fulfilled if any of its requirements is fulfilled. |
| 95 | + |
| 96 | + "OR" logic is applied inside a Group. |
| 97 | + |
| 98 | +.. image:: ../../_static/images/badges/badges-admin-rules-group.png |
| 99 | + :alt: Badge requirement rules group |
| 100 | + |
| 101 | +See `configuration examples`_. |
| 102 | + |
| 103 | +Data Rules |
| 104 | +---------- |
| 105 | + |
| 106 | + Describes **how it is expected to happen** |
| 107 | + |
| 108 | +Data Rules detail their parent Badge Requirement based on the expected event payload. |
| 109 | + |
| 110 | +To edit/update a Data Rule: |
| 111 | + |
| 112 | +- navigate to the Badge Requirement detail page (use ``Change`` inline link); |
| 113 | +- find the "Data Rules" section and add a new item; |
| 114 | + |
| 115 | +.. image:: ../../_static/images/badges/badges-admin-requirement-rules.png |
| 116 | + :alt: Badge requirement rules edit |
| 117 | + |
| 118 | +**Each data rule describes a single expected payload value:** |
| 119 | + |
| 120 | +All key paths are generated based on the event type specified for the parent Badge Requirement. |
| 121 | + |
| 122 | +.. image:: ../../_static/images/badges/badges-admin-data-rules.png |
| 123 | + :alt: Badge requirement data rules |
| 124 | + |
| 125 | +1. **Key path** - payload path to the target attribute |
| 126 | + - dot-separated string; |
| 127 | + - each event type has its unique pre-defined set of key paths; |
| 128 | +2. **Operator** - comparison operation to apply between expected and actual values; |
| 129 | + - available operators: (payload) |
| 130 | + - ``"="`` (equals); |
| 131 | + - ``"!="`` (not equals); |
| 132 | +3. **Expected value** - an expected value for the target attribute |
| 133 | + - payload boolean positive values allowed: ``"true", "True", "yes", "Yes", "+"``; |
| 134 | + - payload boolean negative values allowed: ``"false", "False", "no", "No", "-"``; |
| 135 | + |
| 136 | + |
| 137 | +Please, see `configuration examples`_ for clarity. |
| 138 | + |
| 139 | +Badge Penalties |
| 140 | +--------------- |
| 141 | + |
| 142 | + Penalties allow badge progress resetting based on user activity. |
| 143 | + |
| 144 | +Badge penalties are optional. |
| 145 | +There could be 0 or more badge penalties configured for a badge template. |
| 146 | + |
| 147 | +Each badge penalty is *targeted* to 1 or more badge requirements. |
| 148 | +A penalty setup is similar to a badge requirement, but has different effect: it decreases badge progress for a user. |
| 149 | + |
| 150 | +When all penalty rules have been applied, a learner's progress towards a badge is reset. |
| 151 | + |
| 152 | +.. image:: ../../_static/images/badges/badges-admin-penalty-rules.png |
| 153 | + :alt: Badge penalty rules edit |
| 154 | + |
| 155 | +Activation |
| 156 | +---------- |
| 157 | + |
| 158 | +Configured group can be activated: |
| 159 | + |
| 160 | +- navigate to the group detail page; |
| 161 | +- check ``Is active`` checkbox; |
| 162 | + |
| 163 | + Activated groups starts "working" immediately. |
| 164 | + |
| 165 | +Accredible group record includes: |
| 166 | + |
| 167 | +1. Core credential attributes; |
| 168 | +2. Badge template credential attributes; |
| 169 | +3. Accredible service attributes (dashboard link); |
| 170 | +4. Configured requirements; |
| 171 | + |
| 172 | +.. _`configuration examples`: examples.html |
| 173 | +.. _openedx-events: https://github.com/openedx/openedx-events |
0 commit comments