Cara Membatalkan Open Badge (Dan Apa Yang Berlaku pada Salinan Penerima)

Pembatalan dalam Open Badges: bagaimana ia berfungsi, apa yang berubah untuk penerima, dan cara yang betul untuk menangani kes «dikeluarkan secara silap» berbanding «kredensial tamat tempoh» berbanding «pelanggaran dasar».

Nacho Coll Oleh Dikemas kini 10 minit bacaan
Pembatalan dalam Open Badges: bagaimana ia berfungsi, apa yang berubah untuk penerima, dan cara yang betul untuk menangani kes «dikeluarkan secara silap» berbanding «kredensial tamat tempoh» berbanding «pelanggaran dasar».

Lambat laun, setiap program yang mengeluarkan kredensial digital terpaksa menarik balik satu. Sijil tersalah diberikan kepada orang lain. Seorang pelajar didapati menipu dalam penilaian akhir. Kontrak rakan kongsi tamat dan lencana yang tertulis “Certified Partner” tidak lagi sepatutnya sah. Mengeluarkan ialah bahagian yang menggembirakan; pembatalan ialah bahagian yang menentukan sama ada kredensial anda benar-benar boleh dipercayai.

Panduan ini menerangkan cara pembatalan berfungsi dalam Open Badges, apa yang penerima lihat dan tidak lihat selepas itu, dan cara membatalkan satu kredensial atau beberapa ratus di https://badges.ninja, daripada papan pemuka atau melalui API.

Apa maksud “batal” dalam Open Badges

Dalam spesifikasi Open Badges v2.0, setiap lencana yang dikeluarkan ialah satu assertion: dokumen JSON-LD kecil yang dihoskan pada URL awam dan menyatakan “pengeluar ini menganugerahkan lencana ini kepada penerima ini pada tarikh ini.” Pembatalan hanyalah perubahan pada dokumen yang dihoskan itu. Assertion tersebut mendapat "revoked": true, dan secara pilihan rentetan "revocationReason" yang menjelaskan sebabnya.

Reka bentuk itu membawa akibat penting yang mengejutkan ramai pemilik program:

  • Assertion yang dihoskan ialah sumber kebenaran. Sesiapa yang mengesahkan kredensial dengan mendapatkan URL assertion atau membuka halaman pengesahan akan melihat status dibatalkan serta-merta.
  • Salinan tidak ditarik balik. Jika penerima memuat turun imej lencana atau JSON, atau menyematkannya pada portfolio, fail itu tidak berubah. Ia masih mengandungi pautan kembali ke assertion anda yang dihoskan, jadi pengesah yang mengikut pautan itu akan melihat ia telah dibatalkan, tetapi orang yang sekadar melihat PNG yang disimpan tidak akan nampak.

Oleh itu, pembatalan ialah satu pernyataan pada titik akhir pengesahan, bukan pemadaman. Anggaplah ia seperti mengecap “VOID” pada rekod induk, bukannya mengejar setiap salinan fotokopi.

Jika anda mahu melihat dokumen itu dengan lebih dekat, panduan Open Badge JSON-LD kami membincangkan setiap medan.

Batal, keluarkan semula, atau padam: pilih tindakan yang betul

Sebelum mengklik apa-apa, tentukan antara tiga tindakan yang mana sesuai dengan situasi anda. Ia tidak boleh ditukar ganti.

SituasiTindakan terbaikSebab
Kredensial dikeluarkan kepada orang yang salah atau ada kesilapan ejaanPadam (jika belum dihantar) atau Batal, kemudian keluarkan semulaPadam membuang rekod sepenuhnya; batal mengekalkan jejak audit
Pelajar melanggar dasar atau kredensial diperoleh secara tidak wajarBatal, dengan sebabRekod kekal boleh disahkan sebagai dibatalkan, itulah yang anda perlukan dalam pertikaian
Kredensial hanya sampai tarikh tamatTiada tindakan; tetapkan tarikh luput semasa mengeluarkanTamat tempoh ialah peristiwa kitaran hayat biasa, bukan pembatalan
Program dibatalkan, kohort dibatalkanBatal secara pukalSatu kerja, satu sebab, dikenakan kepada semua orang
Butiran salah tetapi kredensial selebihnya sahEdit sebelum dihantar, atau batal dan keluarkan semula selepas dihantarMemastikan pengalaman penerima kekal bersih

Dua peraturan asas:

  1. Pilih batal berbanding padam untuk apa-apa yang benar. Halaman awam kredensial yang dipadam memulangkan ralat tidak ditemui. Kredensial yang dibatalkan masih boleh dicapai dan dengan jelas menyatakan ia dibatalkan, iaitu bukti yang jauh lebih baik jika ada yang bertanya kemudian apa yang berlaku.
  2. Jangan sekali-kali gunakan pembatalan sebagai pengganti tamat tempoh. Jika kredensial hanya sah selama dua tahun, tetapkan tarikh luput semasa anda mengeluarkannya. Lencana yang luput secara senyap berbeza daripada yang ditarik balik, dan halaman pengesahan anda harus menyatakan yang mana satu.

Membatalkan daripada papan pemuka

Untuk beberapa kredensial sahaja, papan pemuka ialah laluan terpantas dan tidak memerlukan kod.

  1. Log masuk dan buka Awards daripada bar sisi.
  2. Cari kredensial itu. Senarai memaparkan penerima, nama lencana, tarikh dikeluarkan dan tarikh luput, dan anda boleh mencari mengikut penerima.
  3. Klik baris itu (atau View) untuk membuka modal butiran kredensial.
  4. Klik Revoke.
  5. Dalam dialog pengesahan, masukkan sebab secara pilihan, dan tandakan Email the recipient that their credential was revoked secara pilihan.
  6. Sahkan.

Award detail modal

Kredensial kekal dalam senarai anda dengan cip merah Revoked di sebelah penerima, supaya anda dan pasukan anda sentiasa dapat melihat apa yang ditarik balik. Pembatalan tidak memulangkan kredensial kepada kuota pelan anda. Anda telah mengeluarkannya, ia sudah dikira.

Catatan tentang medan sebab

Sebab itu pilihan, tetapi isikanlah. Ia disimpan bersama kredensial, muncul sebagai revocationReason dalam assertion Open Badges awam, dan disertakan dalam payload webhook yang diterima sistem anda. Oleh sebab ia awam pada assertion, tulislah seperti anda menulis untuk pembaca luar. “Dikeluarkan secara silap” atau “Program dibatalkan” tidak mengapa. “Jane menipu pada soalan 14” tidak boleh. Simpan butiran peribadi dalam rekod anda sendiri dan kekalkan sebab awam yang neutral.

Perlukah anda e-mel penerima?

Biasanya ya. Pelajar yang hanya mengetahui kredensialnya sudah tidak sah apabila majikan mengklik pautan pengesahan berhak untuk tidak berpuas hati dengan anda. Pemberitahuan itu bersifat pilihan kerana sesetengah pembatalan (contohnya pembersihan pukal anugerah ujian) tidak perlu mengganggu sesiapa. Panduan kami:

  • E-mel apabila pembatalan menjejaskan orang sebenar yang mungkin masih memaparkan kredensial itu.
  • Langkau e-mel apabila anda mengemas data ujian dalaman atau membatalkan kredensial yang tidak pernah dihantar.

Membatalkan banyak kredensial sekali gus

Program jarang perlu membatalkan satu kredensial secara berasingan; lebih kerap ia melibatkan seluruh kohort. Dalam senarai Awards:

  1. Tandakan kotak semak untuk kredensial yang ingin anda tarik balik.
  2. Klik Revoke selected dalam bar tindakan pukal.
  3. Tambah sebab dan tentukan sama ada hendak memberitahu penerima, kemudian sahkan.

Pembatalan pukal berjalan sebagai kerja latar belakang yang tahan lasak, jadi beberapa ratus kredensial tidak akan menyebabkan tab pelayar anda tamat masa. Kredensial yang sudah dibatalkan dilangkau dan bukannya menggagalkan kelompok, dan kerja yang terhenti separuh jalan boleh disambung semula. Mekanisme yang sama menggerakkan pengeluaran pukal daripada hamparan, yang kami bincangkan dalam cara mengeluarkan Open Badges daripada CSV.

Membatalkan melalui API

Jika sistem pembelajaran atau platform HR anda yang menentukan siapa yang tidak lagi diperakui, anda boleh membatalkan secara atur cara. Titik akhirnya ialah POST /awards/{awardId}/revoke, disahkan dengan kunci API (X-Api-Key: bws_<32-hex>) atau token Bearer Cognito. ID anugerah diletakkan dalam laluan; reason dan notify diletakkan dalam badan JSON dan kedua-duanya pilihan.

Menggunakan 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>"}

Dalam JavaScript:

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

Dan dalam Python:

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

Beberapa butiran praktikal yang berguna untuk diketahui:

  • Ia idempoten. Membatalkan kredensial yang sudah dibatalkan memulangkan respons kejayaan yang sama dan tidak menghantar pemberitahuan kali kedua. Ini menjadikannya selamat dipanggil daripada kerja yang mencuba semula.
  • Sebab dipotong kepada 500 aksara.
  • notify lalai kepada false. Tiada e-mel dihantar melainkan anda memintanya.
  • Pembatalan pukal tersedia melalui titik akhir pukal dengan action: "revoke" dan senarai ID anugerah; ia memulangkan ID kerja yang boleh anda jejaki. Parameter penuh terdapat dalam rujukan API awards.

Anda hanya memerlukan API apabila pembatalan didorong oleh sistem lain. Untuk kes sekali sahaja, papan pemuka lebih pantas dan mempunyai langkah pengesahan yang melindungi anda daripada ID yang tersalah taip.

Apa yang penerima dan pengesah lihat

Selepas anda membatalkan, inilah yang berubah, dan betapa cepatnya.

Pada halaman pengesahan awam. Halaman di https://badges.ninja/awards/<award-id> memaparkan kredensial sebagai dibatalkan, dan tajuk halaman untuk perkongsian sosial diawali dengan “[Revoked]” supaya pautan yang dikongsi tidak kelihatan seperti kredensial yang masih sah dalam kad pratonton.

Dalam assertion Open Badges v2.0. JSON yang dihoskan di https://api.badges.ninja/certify-badge/award/<award-id> kini membawa "revoked": true, serta "revocationReason" jika anda memberikannya. Assertion yang dibatalkan dicache hanya kira-kira 30 saat, manakala yang aktif dicache selama lima minit, jadi perubahan sampai kepada pengesah dengan cepat.

Dalam kredensial Open Badges 3.0. Pembatalan juga menukar bit kredensial dalam W3C Bitstring Status List, iaitu cara dompet verifiable credential dan pengesah mengesannya. Senarai itu dicache seketika, jadi jangkakan penyebaran dalam masa kira-kira seminit. Jika anda menimbang kedua-dua versi, lihat Open Badges v2 vs v3.

Dalam salinan penerima sendiri. Tiada apa-apa yang berubah pada fail yang mereka muat turun. Imej lencana pada komputer riba mereka kelihatan serupa. Apa yang berubah ialah hasil pengesahan: sesiapa yang mengklik pautan atau menyemak kredensial secara atur cara mendapat jawapan dibatalkan. Jika anda memberitahu mereka, mereka juga mempunyai e-mel yang menerangkan sebabnya.

Di LinkedIn. Kredensial yang ditambah pada profil LinkedIn ialah pautan beserta metadata yang menunjuk kembali ke halaman pengesahan anda. LinkedIn tidak menyemak pembatalan bagi pihak anda, jadi entri itu mungkin kekal pada profil, tetapi sesiapa yang mengikut pautan akan sampai ke halaman dibatalkan. Ini satu lagi sebab untuk menghantar pemberitahuan dan meminta penerima membuang entri itu.

Beritahu sistem anda sendiri: webhook

Pembatalan jarang menjadi penghujung cerita di dalam organisasi anda. Pelajar mungkin perlu kehilangan akses kepada sesebuah komuniti, rekod majikan mungkin perlu dikemas kini, atau tag CRM mungkin perlu dibuang. Badges Ninja menghantar peristiwa webhook credential.revoked apabila kredensial dibatalkan, dengan URL anugerah dan sebabnya:

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

Langgan peristiwa itu dan sistem hiliran anda kekal selaras tanpa sesiapa perlu ingat untuk mengemas kininya. Butiran persediaan ada dalam dokumentasi webhook, dan kami membincangkan model peristiwa yang lebih luas dalam webhook setup for badge events.

Dasar pembatalan ringkas yang boleh anda guna hari ini

Alat ialah bahagian yang mudah. Bahagian yang lebih sukar ialah memutuskan lebih awal bila anda akan membatalkan dan siapa yang dibenarkan. Dasar bertulis yang ringkas mengelakkan pertikaian kemudian. Templat yang boleh digunakan:

  1. Alasan pembatalan. Senaraikan: dikeluarkan secara silap, diperoleh melalui salah laku, keperluan tidak lagi dipenuhi (contohnya keahlian tamat), atau program ditarik balik.
  2. Siapa yang memutuskan. Namakan peranan, bukan individu. Hadkan kebenaran membatalkan kepada peranan itu.
  3. Notis. Nyatakan bahawa penerima dimaklumkan melalui e-mel, bersama sebabnya, kecuali kredensial itu tidak pernah dihantar.
  4. Rayuan. Berikan penerima cara untuk membantah keputusan itu dan nyatakan berapa lama anda akan membalas. Jika rayuan berjaya, keluarkan kredensial baharu dan bukannya cuba membatalkan pembatalan, dan sejarah kekal bersih.
  5. Rekod. Simpan nota dalaman tentang siapa yang membatalkan apa dan mengapa, berasingan daripada sebab awam yang neutral.

Terbitkan dasar itu pada halaman yang sama tempat anda menerangkan kredensial, supaya penerima tahu peraturan sebelum mereka mendaftar.

Kesilapan lazim yang perlu dielakkan

  • Memadam sedangkan anda bermaksud membatalkan. Padam adalah kekal dan tidak boleh dibuat asal, dan ia menyebabkan halaman awam hilang. Gunakannya untuk kesilapan sebenar pada kredensial yang belum dilihat sesiapa.
  • Meletakkan butiran peribadi dalam sebab. Ia awam pada assertion.
  • Menjangka salinan yang disimpan berubah. Pembatalan wujud pada titik akhir pengesahan. Beritahu penerima supaya membuang kredensial daripada profil dan portfolio.
  • Membatalkan sebagai ganti tamat tempoh. Gunakan tarikh luput untuk kredensial yang terhad tempoh.
  • Menganggap ada bayaran balik. Kredensial yang dibatalkan masih dikira dalam kuota pelan anda.
  • Melupakan sistem hiliran. Sambungkan webhook supaya akses dan rekod mengikut status kredensial.

Soalan lazim

Bolehkah saya membuat asal pembatalan? Tidak melalui antara muka. Jika anda tersalah batal, keluarkan kredensial baharu kepada penerima. Yang dibatalkan kekal sebagai sebahagian daripada jejak audit.

Adakah penerima perlu melakukan apa-apa? Tidak. Jika anda memilih untuk memberitahu mereka, mereka menerima e-mel. Jika tidak, perubahan berlaku secara senyap pada halaman pengesahan.

Adakah pembatalan berfungsi untuk kredensial yang tidak pernah dihantar? Ya, walaupun untuk kredensial yang belum dihantar dengan kesilapan mudah, anda mungkin lebih suka mengeditnya sebelum dihantar, atau memadamnya jika tiada sesiapa yang pernah melihatnya.

Adakah ada had berapa banyak yang boleh saya batalkan? Pembatalan pukal berjalan sebagai kerja latar belakang yang boleh disambung semula, jadi kelompok besar dikendalikan dalam satu operasi dan bukannya satu demi satu.

Adakah majikan akan melihat bahawa kredensial telah dibatalkan? Sesiapa yang mengesahkannya melalui URL awam atau assertion akan melihat status dibatalkan dan sebabnya, jika anda memberikannya.

Kesimpulan

Membatalkan Open Badge ialah tindakan kecil dengan kesan sebenar terhadap kepercayaan. Lakukannya daripada papan pemuka untuk satu kredensial, gunakan pembatalan pukal untuk kohort, dan gunakan API atau webhook apabila sistem lain yang membuat keputusan. Kekalkan sebab yang neutral, maklumkan mereka yang perlu tahu, dan ingat bahawa pembatalan mengubah apa yang pengesah lihat, bukan fail yang sudah berada di tangan penerima.

Bersedia untuk mengeluarkan kredensial boleh disahkan pertama anda? Mulakan percuma di badges.ninja — pereka visual, halaman pengesahan awam, sijil PDF, output Open Badge v2.0. Tanpa kad kredit.

Nacho Coll

Tentang penulis

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.

Kembali ke Blog

Artikel Berkaitan