Ako odvolať Open Badge (a čo sa stane s kópiou príjemcu)

Odvolanie v Open Badges: ako funguje, čo sa mení pre príjemcu a ako správne riešiť „vydané omylom“, „platnosť skončila“ alebo „porušenie pravidiel“.

Nacho Coll Od Aktualizované 9 min čítania
Odvolanie v Open Badges: ako funguje, čo sa mení pre príjemcu a ako správne riešiť „vydané omylom“, „platnosť skončila“ alebo „porušenie pravidiel“.

Skôr či neskôr musí každý program, ktorý vydáva digitálne osvedčenia, jedno z nich vziať späť. Certifikát sa dostal nesprávnej osobe. Zistilo sa, že účastník podvádzal pri záverečnom hodnotení. Skončila partnerská zmluva a odznaky s nápisom „Certified Partner“ už nemajú platiť. Vydávanie je príjemná časť; odvolanie rozhoduje o tom, či sa vašim osvedčeniam naozaj dá dôverovať.

Táto príručka vysvetľuje, ako odvolanie funguje v Open Badges, čo príjemca potom vidí a čo nie, a ako odvolať jedno osvedčenie alebo niekoľko stoviek na https://badges.ninja — z dashboardu alebo cez API.

Čo znamená „odvolať“ v Open Badges

V špecifikácii Open Badges v2.0 je každý vydaný odznak assertion (tvrdenie): malý dokument JSON-LD zverejnený na verejnej adrese, ktorý hovorí „tento vydavateľ udelil tento odznak tomuto príjemcovi v tento deň“. Odvolanie je jednoducho zmena tohto zverejneného dokumentu. Tvrdenie získa "revoked": true a voliteľne reťazec "revocationReason" s vysvetlením dôvodu.

Tento návrh má dôležitý dôsledok, ktorý prekvapuje mnohých správcov programov:

  • Zverejnené tvrdenie je zdrojom pravdy. Každý, kto osvedčenie overuje načítaním adresy tvrdenia alebo otvorením overovacej stránky, okamžite vidí stav „odvolané“.
  • Kópie sa nevolajú späť. Ak si príjemca stiahol obrázok odznaku alebo JSON, prípadne ho pripol do portfólia, tento súbor sa nezmení. Stále obsahuje odkaz na vaše zverejnené tvrdenie, takže overovateľ, ktorý odkaz otvorí, uvidí, že je odvolané, no človek, ktorý sa len pozrie na uložený súbor PNG, nie.

Odvolanie je teda vyhlásenie na overovacom koncovom bode, nie vymazanie. Predstavte si to ako pečiatku „VOID“ na hlavnom zázname, nie ako naháňanie každej fotokópie.

Ak sa chcete pozrieť na samotný dokument bližšie, náš prehľad Open Badge JSON-LD prechádza každé pole.

Odvolať, znova vydať alebo vymazať: vyberte správnu akciu

Skôr než na niečo kliknete, rozhodnite sa, ktorá z troch akcií sedí na danú situáciu. Nie sú zameniteľné.

SituáciaNajlepšia akciaPrečo
Osvedčenie bolo vydané nesprávnej osobe alebo s preklepomVymazať (ak sa neodoslalo) alebo odvolať, potom znova vydaťVymazanie odstráni záznam úplne; odvolanie zachová auditnú stopu
Účastník porušil pravidlá alebo osvedčenie získal nesprávneOdvolať, s dôvodomZáznam zostane overiteľný ako odvolaný, čo pri spore chcete
Osvedčeniu jednoducho uplynula platnosťNerobte nič; pri vydaní nastavte expiráciuExpirácia je bežná súčasť životného cyklu, nie odvolanie
Program zrušený, kohorta zneplatnenáHromadné odvolanieJedna úloha, jeden dôvod, uplatnený na všetkých
Údaje boli chybné, ale osvedčenie je inak platnéUpraviť pred odoslaním, alebo po odoslaní odvolať a znova vydaťZachová príjemcovi čistý zážitok

Dve pravidlá:

  1. Pri všetkom skutočnom uprednostnite odvolanie pred vymazaním. Verejná stránka vymazaného osvedčenia vráti chybu „nenájdené“. Odvolané sa stále zobrazí a jasne uvádza, že je odvolané, čo je omnoho lepší dôkaz, ak sa niekto neskôr opýta, čo sa stalo.
  2. Nikdy nepoužívajte odvolanie namiesto expirácie. Ak je osvedčenie platné len dva roky, nastavte pri vydaní dátum expirácie. Odznak, ktorému potichu skončila platnosť, je niečo iné ako odznak, ktorý bol stiahnutý, a vaša overovacia stránka by mala povedať, ktorý z nich to je.

Odvolanie z dashboardu

Pre hŕstku osvedčení je dashboard najrýchlejšia cesta a nevyžaduje kód.

  1. Prihláste sa a v bočnom paneli otvorte Awards.
  2. Nájdite osvedčenie. Zoznam zobrazuje príjemcu, názov odznaku, dátum vydania a expiráciu a môžete vyhľadávať podľa príjemcu.
  3. Kliknutím na riadok (alebo View) otvorte detail osvedčenia.
  4. Kliknite na Revoke.
  5. V potvrdzovacom dialógu voliteľne zadajte dôvod a voliteľne zaškrtnite Email the recipient that their credential was revoked.
  6. Potvrďte.

Award detail modal

Osvedčenie zostane vo vašom zozname s červeným štítkom Revoked pri príjemcovi, takže vy aj váš tím vždy vidíte, čo bolo stiahnuté. Odvolanie nevráti osvedčenie do kvóty vášho plánu. Vydali ste ho, započítalo sa.

Poznámka k poľu dôvodu

Dôvod je voliteľný, ale vyplňte ho. Ukladá sa spolu s osvedčením, objaví sa ako revocationReason vo verejnom tvrdení Open Badges a je súčasťou webhook payloadu, ktorý dostanú vaše systémy. Keďže je na tvrdení verejný, píšte ho ako pre vonkajšieho čitateľa. „Vydané omylom“ alebo „Program zrušený“ je v poriadku. „Jana podvádzala pri otázke 14“ nie je. Osobné údaje nechajte vo vlastných záznamoch a verejný dôvod držte neutrálny.

Mali by ste príjemcovi poslať e-mail?

Zvyčajne áno. Účastník, ktorý sa dozvie, že jeho osvedčenie je neplatné, až keď naň zamestnávateľ klikne v overení, má plné právo byť na vás nahnevaný. Oznámenie je voliteľné práve preto, že niektoré odvolania (napríklad hromadné upratovanie testovacích ocenení) nemusia nikoho obťažovať. Naše odporúčanie:

  • Pošlite e-mail, keď sa odvolanie týka skutočnej osoby, ktorá môže osvedčenie stále zobrazovať.
  • E-mail vynechajte, keď upratujete interné testovacie dáta alebo zneplatňujete osvedčenia, ktoré sa nikdy neodoslali.

Odvolanie viacerých osvedčení naraz

Programy len zriedka potrebujú odvolať jedno osvedčenie osamote; častejšie ide o celú kohortu. V zozname Awards:

  1. Zaškrtnite políčka osvedčení, ktoré chcete stiahnuť.
  2. V paneli hromadných akcií kliknite na Revoke selected.
  3. Pridajte dôvod, rozhodnite sa, či upozorniť príjemcov, a potvrďte.

Hromadné odvolanie beží ako odolná úloha na pozadí, takže niekoľko stoviek osvedčení neprekročí časový limit vašej karty prehliadača. Už odvolané osvedčenia sa preskočia namiesto zlyhania celej dávky a úlohu prerušenú v polovici možno obnoviť. Rovnaký mechanizmus poháňa hromadné vydávanie z tabuľky, o ktorom píšeme v ako vydávať Open Badges z CSV.

Odvolanie cez API

Ak váš vzdelávací systém alebo HR platforma rozhoduje, kto už nie je certifikovaný, môžete odvolávať programovo. Koncový bod je POST /awards/{awardId}/revoke, autentifikovaný API kľúčom (X-Api-Key: bws_<32-hex>) alebo tokenom Cognito Bearer. ID ocenenia ide do cesty; reason a notify idú do tela JSON a oba sú voliteľné.

Pomocou curl:

curl -X POST https://api.badges.ninja/awards/<award-id>/revoke \
  -H "X-Api-Key: bws_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{"reason":"Issued to the wrong recipient","notify":true}'
# 200 -> {"revoked":true,"awardId":"<award-id>"}

V JavaScripte:

const res = await fetch(`https://api.badges.ninja/awards/${awardId}/revoke`, {
  method: "POST",
  headers: { "X-Api-Key": API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({ reason: "Program cancelled", notify: false }),
});
const { revoked } = await res.json(); // true

A v Pythone:

import requests
res = requests.post(
    f"https://api.badges.ninja/awards/{award_id}/revoke",
    headers={"X-Api-Key": API_KEY},
    json={"reason": "Program cancelled", "notify": False},
)
print(res.json()["revoked"])  # True

Niekoľko praktických detailov, ktoré sa oplatí vedieť:

  • Operácia je idempotentná. Odvolanie už odvolaného osvedčenia vráti rovnakú úspešnú odpoveď a neodošle druhé oznámenie. Vďaka tomu je bezpečné volať ju z úlohy s opakovanými pokusmi.
  • Dôvody sa skracujú na 500 znakov.
  • notify je predvolene false. Nič sa neodošle e-mailom, kým o to nepožiadate.
  • Hromadné odvolanie je dostupné cez hromadný koncový bod s action: "revoke" a zoznamom ID ocenení; vráti ID úlohy, ktorú môžete sledovať. Úplné parametre nájdete v API referencii awards.

API potrebujete len vtedy, keď odvolanie riadi iný systém. Pri jednorazovom prípade je dashboard rýchlejší a má potvrdzovací krok, ktorý vás chráni pred preklepom v ID.

Čo vidí príjemca a overovateľ

Po odvolaní sa mení nasledovné, a to takto rýchlo.

Na verejnej overovacej stránke. Stránka na https://badges.ninja/awards/<award-id> zobrazuje osvedčenie ako odvolané a titulok pri zdieľaní na sociálnych sieťach má predponu „[Revoked]“, aby zdieľaný odkaz v náhľadovej karte nevyzeral ako platné osvedčenie.

V tvrdení Open Badges v2.0. Zverejnený JSON na https://api.badges.ninja/certify-badge/award/<award-id> teraz nesie "revoked": true, plus "revocationReason", ak ste ho uviedli. Odvolané tvrdenia sa cachujú len asi 30 sekúnd, kým platné päť minút, takže zmena sa k overovateľom dostane rýchlo.

V osvedčení Open Badges 3.0. Odvolanie tiež prepne bit osvedčenia v zozname W3C Bitstring Status List, vďaka čomu ho zistia peňaženky overiteľných osvedčení a overovatelia. Tento zoznam sa cachuje krátko, takže počítajte s propagáciou do približne minúty. Ak zvažujete obe verzie, pozrite si Open Badges v2 vs v3.

V kópii samotného príjemcu. Na súbore, ktorý si stiahol, sa nemení nič. Obrázok odznaku na jeho notebooku vyzerá rovnako. Zmení sa výsledok overenia: každý, kto klikne na odkaz alebo osvedčenie skontroluje programovo, dostane odpoveď „odvolané“. Ak ste ho upozornili, má aj e-mail s vysvetlením, prečo.

Na LinkedIne. Osvedčenie pridané do profilu na LinkedIne je odkaz plus metadáta smerujúce na vašu overovaciu stránku. LinkedIn za vás odvolanie nekontroluje, takže záznam môže na profile zostať, ale každý, kto odkaz otvorí, skončí na stránke odvolaného osvedčenia. To je ďalší dôvod poslať oznámenie a požiadať príjemcu, aby záznam odstránil.

Dajte vedieť vlastným systémom: webhooky

Odvolanie je v rámci vašej organizácie len zriedka koniec príbehu. Účastník môže stratiť prístup do komunity, môže sa musieť aktualizovať záznam zamestnávateľa alebo odstrániť značka v CRM. Badges Ninja pri odvolaní osvedčenia vysiela webhook udalosť credential.revoked s adresou ocenenia a dôvodom:

{
  "awardId": "https://api.badges.ninja/certify-badge/award/<award-id>",
  "reason": "Issued in error"
}

Prihláste sa na jej odber a vaše nadväzujúce systémy zostanú synchronizované bez toho, aby si niekto musel pamätať ich aktualizáciu. Podrobnosti nastavenia sú v dokumentácii webhookov a širší model udalostí rozoberáme v nastavenie webhookov pre udalosti odznakov.

Jednoduchá politika odvolávania, ktorú môžete prijať už dnes

Nástroje sú ľahšia polovica. Ťažšia je vopred rozhodnúť, kedy budete odvolávať a kto to smie. Krátka písomná politika neskôr predchádza sporom. Použiteľná šablóna:

  1. Dôvody odvolania. Vymenujte ich: vydané omylom, získané nekalým spôsobom, požiadavka už nie je splnená (napríklad skončilo členstvo) alebo program stiahnutý.
  2. Kto rozhoduje. Pomenujte rolu, nie osobu. Právo odvolávať obmedzte na túto rolu.
  3. Oznámenie. Uveďte, že príjemcovia sú informovaní e-mailom s dôvodom, pokiaľ osvedčenie nebolo nikdy doručené.
  4. Odvolanie sa (appeal). Dajte príjemcom spôsob, ako rozhodnutie napadnúť, a uveďte, ako dlho budete odpovedať. Ak námietka uspeje, vydajte nové osvedčenie namiesto pokusu o zrušenie odvolania a história zostane čistá.
  5. Záznam. Vedzte interné poznámky, kto čo odvolal a prečo, oddelene od neutrálneho verejného dôvodu.

Politiku zverejnite na rovnakej stránke, kde osvedčenie popisujete, aby držitelia poznali pravidlá skôr, než sa zaregistrujú.

Časté chyby, ktorým sa vyhnúť

  • Vymazanie, keď ste chceli odvolať. Vymazanie je trvalé a nedá sa vrátiť späť a verejná stránka zmizne. Používajte ho pre skutočné chyby pri osvedčeniach, ktoré nikto nevidel.
  • Súkromné údaje v dôvode. Je verejný na tvrdení.
  • Očakávanie, že sa uložené kópie zmenia. Odvolanie žije na overovacom koncovom bode. Povedzte príjemcom, aby osvedčenie odstránili z profilov a portfólií.
  • Odvolanie namiesto expirácie. Pre časovo obmedzené osvedčenia použite dátum expirácie.
  • Predpoklad vrátenia kvóty. Odvolané osvedčenia sa naďalej počítajú do kvóty vášho plánu.
  • Zabudnutie na nadväzujúce systémy. Prepojte webhook, aby prístupy a záznamy nasledovali stav osvedčenia.

Často kladené otázky

Môžem odvolanie vrátiť späť? Nie cez rozhranie. Ak ste odvolali omylom, vydajte príjemcovi nové osvedčenie. Odvolané zostane ako súčasť auditnej stopy.

Musí príjemca niečo urobiť? Nie. Ak ste sa rozhodli ho upozorniť, dostane e-mail. Inak sa zmena odohrá potichu na overovacej stránke.

Funguje odvolanie aj pri osvedčeniach, ktoré sa nikdy neodoslali? Áno, hoci pri neodoslanom osvedčení s jednoduchou chybou môžete uprednostniť úpravu pred odoslaním alebo vymazanie, ak ho nikto nevidel.

Existuje limit, koľko môžem odvolať? Hromadné odvolanie beží ako obnoviteľná úloha na pozadí, takže veľké dávky sa spracujú jednou operáciou namiesto jednotlivo.

Uvidia zamestnávatelia, že osvedčenie bolo odvolané? Každý, kto ho overuje cez verejnú adresu alebo tvrdenie, vidí stav odvolania a dôvod, ak ste ho uviedli.

Záver

Odvolanie Open Badge je malá akcia s reálnymi dôsledkami pre dôveru. Robte ho z dashboardu, keď ide o jedno osvedčenie, použite hromadné odvolanie pri kohorte a siahnite po API alebo webhookoch, keď rozhodnutie vlastní iný systém. Držte dôvody neutrálne, informujte ľudí, ktorí to potrebujú vedieť, a pamätajte, že odvolanie mení to, čo vidia overovatelia, nie súbory, ktoré už príjemcovia držia.

Ste pripravení vydať svoje prvé overiteľné osvedčenie? Začnite zadarmo na badges.ninja — vizuálny dizajnér, verejná overovacia stránka, PDF certifikát, výstup Open Badge v2.0. Bez kreditnej karty.

Nacho Coll

O autorovi

Founder & Engineer at Badges Ninja

Nacho founded Badges Ninja to make issuing verifiable digital credentials as simple as a single API call — Open Badge v2.0 badges and certificates, minted, hosted, and verifiable without standing up your own issuer infrastructure. Writes about the Open Badges spec, credential verification, and running a credentialing platform serverless on AWS, from the operator side of the wire.

Späť na blog

Súvisiace články