Salesforce Open Badges: Mengeluarkan Kelayakan Boleh Disahkan daripada Pencetus CRM

Kebanyakan pasukan latihan sudah merekodkan dalam Salesforce siapa yang telah menamatkan apa. Pendaftaran kursus bertukar kepada “Completed”, akaun rakan kongsi mencapai tahap pensijilan, pelanggan selesai menjalani onboarding. Rekod berubah, kemudian seminggu selepas itu seseorang mengeksport senarai dan menghantar sijil melalui e-mel secara manual.

Panduan ini menunjukkan cara menutup jurang itu: apabila rekod mencapai status yang anda mahukan, Salesforce memanggil API https://badges.ninja, kelayakan Open Badge v2.0 dikeluarkan, dan pautan pengesahan disimpan semula pada rekod. Anda kemudian boleh meletakkan pautan itu dalam templat e-mel, laporan, atau halaman Experience Cloud.

Anda memerlukan pentadbir Salesforce (atau sandbox pembangun), lencana yang sudah direka di https://badges.ninja, dan kunci API. Jika anda belum pernah memanggil API sebelum ini, baca API quickstart dahulu; ia mengambil masa sepuluh minit.

Bila pencetus CRM ialah alat yang tepat

Sebelum menulis Apex, semak sama ada anda memerlukannya. Jika anda mengeluarkan kelayakan secara berkelompok sekali setiap penggal atau sekali setiap suku tahun, muat naik CSV di papan pemuka lebih pantas dan tidak memerlukan kod langsung. Laluan Salesforce berbaloi apabila:

• Pengeluaran perlu berlaku sebaik sahaja rekod berubah, tanpa langkah manusia.
• Data “siapa yang memperolehnya” sudah ada dalam Salesforce dan anda tidak mahu sumber kebenaran kedua.
• Anda mahu pautan kelayakan disimpan pada Contact, Lead, atau rekod latihan tersuai untuk tujuan pelaporan.

Jika alat aliran kerja anda ialah Zapier dan bukan Apex, panggilan API yang sama berfungsi di sana juga; lihat Zapier Open Badges automation.

Apa yang anda bina

Aliran ini mempunyai empat bahagian:

1. Lencana yang direka dalam pereka visual. Salin id-nya (id yang dikembalikan oleh GET /badges).
2. Kunci API yang dicipta di halaman API Keys papan pemuka anda. Kunci ditunjukkan sekali sahaja, jadi simpan terus.
3. Named Credential dalam Salesforce yang menyimpan kunci itu, supaya ia tidak pernah muncul dalam kod.
4. Pencetus Apex dan kelas Queueable yang mengeluarkan anugerah dan menulis pautan anugerah semula ke rekod.

Langkah 1: Simpan kunci dalam Named Credential

Menulis kunci API terus dalam Apex ialah kesilapan yang perlu dielakkan. Dalam Setup, cipta External Credential dengan pengepala tersuai, kemudian Named Credential yang menuju ke hos API:

• URL: https://api.badges.ninja
• Nama pengepala tersuai: X-Api-Key
• Nilai pengepala tersuai: kunci anda, dalam bentuk bws_YOUR_KEY_HERE
• Nama Named Credential: BadgesNinja

Berikan permission set yang menjalankan automasi anda akses kepada principal External Credential. Dengan Named Credential, anda tidak memerlukan Remote Site Setting yang berasingan; Salesforce membenarkan panggilan melalui credential tersebut. Jika org anda masih menggunakan Named Credential lama atau endpoint biasa, tambahkan https://api.badges.ninja sebagai Remote Site Setting dan hantar pengepala daripada kod.

Langkah 2: Tambah medan pada rekod

Pada objek yang mewakili pencapaian (kita akan menggunakan objek tersuai bernama Training_Enrollment__c), tambahkan:

• Badge_Id__c (Text): lencana yang hendak dikeluarkan. Menyimpannya bagi setiap kursus membolehkan satu pencetus melayan banyak lencana.
• Badge_Award_Id__c (Text, unique): id anugerah yang dikembalikan oleh API.
• Badge_Url__c (URL): halaman pengesahan awam.
• Badge_Error__c (Long Text): ralat terakhir, supaya pentadbir dapat melihat kegagalan tanpa membuka log nyahpepijat.

Medan Badge_Award_Id__c berfungsi dua kali. Ia ialah pengawal pendua anda: pencetus hanya mengeluarkan apabila medan ini kosong.

Langkah 3: Panggilan Apex

Pencetus tidak boleh membuat panggilan keluar secara terus, kerana panggilan keluar tidak dibenarkan dalam transaksi yang sama dengan DML yang belum di-commit. Serahkan kerja itu kepada Queueable yang melaksanakan Database.AllowsCallouts.

Kontrak API untuk POST /awards adalah ringkas. Badan permintaan membawa badgeId, objek recipient bersarang dengan name dan email, serta issuedOn yang diwajibkan. Panggilan yang berjaya mengembalikan HTTP 200 dengan { "awardId": "..." }. Nama penerima mestilah sekurang-kurangnya lima aksara, jadi Contact bernama “Al Li” akan ditolak; sahkan sebelum anda membuat panggilan.

public class BadgeIssueJob implements Queueable, Database.AllowsCallouts {
    private Id enrollmentId;
    public BadgeIssueJob(Id enrollmentId) { this.enrollmentId = enrollmentId; }

    public void execute(QueueableContext ctx) {
        Training_Enrollment__c e = [
            SELECT Id, Badge_Id__c, Badge_Award_Id__c, Contact__r.Name, Contact__r.Email
            FROM Training_Enrollment__c WHERE Id = :enrollmentId LIMIT 1
        ];
        if (e.Badge_Award_Id__c != null) { return; }   // already issued

        Map<String, Object> recipient = new Map<String, Object>{
            'name' => e.Contact__r.Name,
            'email' => e.Contact__r.Email
        };
        Map<String, Object> body = new Map<String, Object>{
            'badgeId' => e.Badge_Id__c,
            'recipient' => recipient,
            'issuedOn' => Datetime.now().getTime()
        };

        HttpRequest req = new HttpRequest();
        req.setEndpoint('callout:BadgesNinja/awards');
        req.setMethod('POST');
        req.setHeader('Content-Type', 'application/json');
        req.setBody(JSON.serialize(body));

        HttpResponse res = new Http().send(req);
        if (res.getStatusCode() == 200) {
            Map<String, Object> out = (Map<String, Object>) JSON.deserializeUntyped(res.getBody());
            String awardId = (String) out.get('awardId');
            e.Badge_Award_Id__c = awardId;
            e.Badge_Url__c = 'https://badges.ninja/awards/' + awardId;
            e.Badge_Error__c = null;
        } else {
            e.Badge_Error__c = res.getStatusCode() + ': ' + res.getBody();
        }
        update e;
    }
}

Dua perkara yang patut diberi perhatian. Pertama, issuedOn ialah milisaat epoch, iaitu tepat seperti yang dikembalikan oleh Datetime.getTime(). Kedua, respons tidak menyertakan URL pengesahan, jadi kod membinanya daripada id anugerah: https://badges.ninja/awards/<awardId>.

Langkah 4: Pencetus

Pastikan pencetus ringkas. Ia hanya menentukan rekod mana yang layak dan memasukkan satu tugas ke dalam baris gilir bagi setiap rekod.

trigger TrainingEnrollmentBadge on Training_Enrollment__c (after insert, after update) {
    for (Training_Enrollment__c e : Trigger.new) {
        Boolean completed = e.Status__c == 'Completed';
        Boolean wasCompleted = Trigger.isUpdate && Trigger.oldMap.get(e.Id).Status__c == 'Completed';
        if (completed && !wasCompleted && e.Badge_Award_Id__c == null && e.Badge_Id__c != null) {
            System.enqueueJob(new BadgeIssueJob(e.Id));
        }
    }
}

Semakan wasCompleted penting. Tanpanya, sebarang suntingan kemudian pada rekod yang telah selesai akan mencetuskan semula logik. Digabungkan dengan pengawal id anugerah kosong dalam tugas, satu rekod hanya boleh menghasilkan satu kelayakan.

Satu had yang perlu dipatuhi: Salesforce membenarkan sebilangan kecil tugas Queueable dimasukkan ke baris gilir daripada satu transaksi (50 dalam konteks segerak). Jika anda memuatkan penyelesaian secara pukal, katakan import data 2,000 baris, pencetus di atas akan mencecah had itu. Untuk muatan pukal, sama ada muat naik senarai melalui anugerah pukal CSV papan pemuka, atau beralih kepada kelas Batchable dengan Database.AllowsCallouts yang memproses beberapa rekod bagi setiap skop.

Pengendalian ralat dan percubaan semula

API mengembalikan kod status piawai, dan setiap satu memerlukan tindak balas yang berbeza daripada kod anda:

Oleh sebab tugas menulis ralat ke rekod dan membiarkan Badge_Award_Id__c kosong, percubaan semula semudah menukar kotak semak atau menyimpan semula rekod. Kelas Apex berjadual kecil yang mencari pendaftaran selesai tanpa id anugerah dan dengan ralat sementara, kemudian memasukkannya semula ke baris gilir, memberi anda baris gilir percubaan semula automatik tanpa infrastruktur tambahan. Hadkan bilangan percubaan dengan medan pembilang supaya rekod yang sentiasa bermasalah tidak berulang selama-lamanya.

Semak pelan anda sebelum menyambungkannya ke pengeluaran. Pelan Free meliputi 1,200 kelayakan setahun; Starter ialah $9 sebulan dan Pro ialah $29 sebulan. Pencetus yang aktif pada setiap Lead akan menghabiskan pelan kecil dengan cepat, jadi hadkan kriteria kepada pencapaian sebenar.

Menjadikan kelayakan kelihatan dalam Salesforce

Sebaik sahaja Badge_Url__c diisi, anda boleh menggunakannya di mana-mana:

• Amaran e-mel dan templat: gabungkan medan itu ke dalam e-mel “Tahniah, ini kelayakan anda”.
• Laporan: laporan pada Badge_Award_Id__c != null memberi anda kiraan pengeluaran mengikut kursus, wilayah, atau pemilik akaun.
• Experience Cloud: paparkan pautan pada halaman pensijilan rakan kongsi supaya pembeli boleh mengesahkannya sendiri.
• Susun atur halaman: tambahkan medan URL supaya kakitangan sokongan dapat menjawab “adakah dia sudah dapat lencananya?” sekilas pandang.

Halaman pengesahan adalah awam dan tidak memerlukan pendaftaran, dan itulah intinya. Penerima, pengurus pengambilan pekerja, atau pasukan perolehan pelanggan boleh membuka pautan dan mengesahkan siapa yang mengeluarkan kelayakan, apa yang disahkannya, dan bila. Untuk semakan oleh mesin, JSON-LD Open Badge v2.0 bagi mana-mana anugerah tersedia di https://api.badges.ninja/certify-badge/award/<awardId>.

Penerima juga mendapat tambahan biasa: URL pengesahan unik, kod QR, sijil PDF A4, dan pilihan Add to LinkedIn daripada portal penerima, yang log masuk dengan pautan ajaib dan bukannya kata laluan.

Mengapa ini lebih baik daripada pemalam lencana AppExchange

Pemalam lencana di AppExchange cenderung dihargakan mengikut kerusi Salesforce atau lesen managed package. Kos itu meningkat mengikut saiz pasukan Salesforce anda, bukan mengikut bilangan kelayakan yang anda keluarkan, jadi pasukan latihan sepuluh orang dan program sepuluh ribu pelajar membayar dengan sangat berbeza untuk hasil yang sama.

Integrasi API membalikkan model itu. Anda membayar mengikut volum kelayakan pada pelan tetap, kod pencetus boleh anda baca dan ubah, dan hasilnya ialah Open Badge v2.0 piawai, jadi penerima tidak terkunci dalam pemapar proprietari. Anda juga mengekalkan kebebasan reka bentuk: pereka visual menawarkan 80+ templat, bentuk, ikon, dan muat naik tersuai, bukannya susun atur tetap dalam sebuah pakej.

Pertukaran yang jujur: pemalam hanya perlu diklik untuk dipasang dan tidak memerlukan Apex. Jika tiada sesiapa dalam pasukan anda yang boleh menyelenggara beberapa puluh baris kod, pemalam atau penyambung tanpa kod mungkin lebih sesuai. Jika anda membandingkan platform secara umum dan bukan integrasi, ulasan Credly alternative merangkumi perbezaan harga dan ciri secara bersebelahan.

Menguji sebelum tayangan langsung

Jalankan keseluruhan aliran dalam sandbox terlebih dahulu.

1. Cipta lencana ujian dan penerima ujian dengan alamat e-mel yang anda kawal.
2. Dalam ujian Apex, laksanakan HttpCalloutMock yang mengembalikan status 200 dan {"awardId":"test-award-id"}; Salesforce tidak membenarkan panggilan keluar sebenar dalam konteks ujian, dan anda memerlukan liputan itu untuk deploy.
3. Dalam sandbox, tetapkan satu pendaftaran kepada Completed dan semak bahawa Badge_Award_Id__c dan Badge_Url__c terisi dalam masa seminit.
4. Buka URL dalam tetingkap pelayar peribadi untuk mengesahkan halaman pengesahan awam dipaparkan tanpa log masuk.
5. Paksa kegagalan (kosongkan id lencana, atau gunakan nama penerima kurang daripada lima aksara) dan sahkan ralat mendarat dalam Badge_Error__c.

Putar kunci API jika ia pernah bocor ke dalam log nyahpepijat atau tangkapan skrin. Pembatalan berlaku serta-merta dari halaman API Keys, dan anda hanya perlu mengemas kini External Credential, bukan kod anda.

Penutup

Coraknya kecil: pencetus ringkas menentukan bila, Queueable membuat panggilan, Named Credential menyimpan kunci, dan tiga medan pada rekod menyimpan hasilnya. Ia berfungsi untuk pencapaian latihan, tahap rakan kongsi, kehadiran acara, atau sebarang perubahan keadaan yang boleh anda ungkapkan dalam Salesforce.

Mulakan dengan satu objek dan satu lencana, pantau selama seminggu, dan kembangkan selepas tingkah laku percubaan semula sesuai dengan data anda.

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