Salesforce Open Badges: izdavanje provjerljivih vjerodajnica iz CRM okidača

Većina edukacijskih timova već bilježi u Salesforceu tko je što završio. Upis na tečaj prelazi u «Completed», partnerski račun dosegne razinu certifikacije, klijent završi onboarding. Zapis se promijeni, a tjedan dana kasnije netko izveze popis i ručno razašalje certifikate e-poštom.

Ovaj vodič pokazuje kako zatvoriti taj jaz: kad zapis dosegne status koji vas zanima, Salesforce poziva https://badges.ninja API, izdaje se Open Badge v2.0 vjerodajnica, a poveznica za provjeru sprema se natrag u zapis. Tu poveznicu zatim možete ubaciti u predložak e-pošte, izvješće ili stranicu u Experience Cloudu.

Trebat će vam Salesforce administrator (ili developer sandbox), značka koju ste već dizajnirali na https://badges.ninja i API ključ. Ako još nikad niste pozvali API, prvo pročitajte API quickstart; traje deset minuta.

Kada je CRM okidač pravi alat

Prije pisanja Apexa provjerite treba li vam uopće. Ako vjerodajnice izdajete u serijama jednom u semestru ili jednom u tromjesečju, CSV učitavanje na nadzornoj ploči brže je i ne traži nikakav kod. Salesforce put se isplati kada:

• se izdavanje treba dogoditi u trenutku promjene zapisa, bez ljudskog koraka.
• podaci o tome «tko je to zaslužio» već žive u Salesforceu i ne želite drugi izvor istine.
• želite pohraniti poveznicu na vjerodajnicu u Contact, Lead ili prilagođeni edukacijski zapis radi izvještavanja.

Ako je vaš alat za tijekove rada Zapier, a ne Apex, isti API poziv radi i ondje; pogledajte Zapier Open Badges automation.

Što gradite

Tijek ima četiri dijela:

1. Značku dizajniranu u vizualnom dizajneru. Kopirajte njezin id (id koji vraća GET /badges).
2. API ključ izrađen na stranici API Keys na vašoj nadzornoj ploči. Ključ se prikazuje samo jednom, zato ga odmah pohranite.
3. Named Credential u Salesforceu koji drži ključ kako se nikad ne bi pojavio u kodu.
4. Apex okidač i Queueable klasu koji izdaju award i upisuju poveznicu na award natrag u zapis.

Korak 1: pohranite ključ u Named Credential

Ugrađivanje API ključa izravno u Apex pogreška je koju treba izbjeći. U Setupu izradite External Credential s prilagođenim zaglavljem, a zatim Named Credential koji pokazuje na API host:

• URL: https://api.badges.ninja
• Custom header name: X-Api-Key
• Custom header value: vaš ključ, u obliku bws_YOUR_KEY_HERE
• Named Credential name: BadgesNinja

Dodijelite permission setu koji pokreće vašu automatizaciju pristup principalu External Credentiala. S Named Credentialom ne trebate zaseban Remote Site Setting; Salesforce autorizira poziv putem vjerodajnice. Ako vaš org još koristi legacy Named Credentials ili običan endpoint, dodajte https://api.badges.ninja kao Remote Site Setting i zaglavlje šaljite iz koda.

Korak 2: dodajte polja u zapis

Na objekt koji predstavlja postignuće (koristit ćemo prilagođeni objekt Training_Enrollment__c) dodajte:

• Badge_Id__c (Text): značka koju treba izdati. Ako je pohranite po tečaju, jedan okidač može služiti mnogim značkama.
• Badge_Award_Id__c (Text, unique): id awarda koji vraća API.
• Badge_Url__c (URL): javna stranica za provjeru.
• Badge_Error__c (Long Text): posljednja pogreška, kako bi administratori vidjeli neuspjehe bez otvaranja debug logova.

Polje Badge_Award_Id__c ima dvostruku ulogu. To je vaša zaštita od duplikata: okidač izdaje samo kada je prazno.

Korak 3: Apex callout

Okidač ne može izravno napraviti callout jer callouti nisu dopušteni u istoj transakciji s nepotvrđenim DML-om. Posao prepustite Queueable klasi koja implementira Database.AllowsCallouts.

API ugovor za POST /awards kratak je. Tijelo nosi badgeId, ugniježđeni objekt recipient s poljima name i email te obvezni issuedOn. Uspješan poziv vraća HTTP 200 s { "awardId": "..." }. Ime primatelja mora imati najmanje pet znakova, pa bi Contact imena «Al Li» bio odbijen; validirajte prije poziva.

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;
    }
}

Dva detalja vrijedna pažnje. Prvo, issuedOn je epoch u milisekundama, što je upravo ono što vraća Datetime.getTime(). Drugo, odgovor ne uključuje URL za provjeru, pa ga kod gradi iz id-a awarda: https://badges.ninja/awards/<awardId>.

Korak 4: okidač

Okidač neka bude tanak. On samo odlučuje koji zapisi ispunjavaju uvjete i stavlja u red jedan job po zapisu.

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));
        }
    }
}

Provjera wasCompleted je važna. Bez nje bi svaka kasnija izmjena završenog zapisa ponovno pokrenula logiku. U kombinaciji sa zaštitom od praznog id-a awarda unutar joba, zapis može proizvesti samo jednu vjerodajnicu.

Jedno ograničenje treba poštovati: Salesforce dopušta mali broj Queueable jobova u redu iz jedne transakcije (50 u sinkronom kontekstu). Ako masovno učitavate završene upise, recimo uvoz od 2.000 redaka, gornji će okidač udariti u taj limit. Za masovna učitavanja ili učitajte popis putem CSV masovnih awarda na nadzornoj ploči, ili prijeđite na Batchable klasu s Database.AllowsCallouts koja obrađuje nekoliko zapisa po scopeu.

Obrada pogrešaka i ponovni pokušaji

API vraća standardne statusne kodove, a svaki traži drukčiji odgovor vašeg koda:

Budući da job upisuje pogrešku u zapis i ostavlja Badge_Award_Id__c praznim, ponovni pokušaj jednostavan je poput prebacivanja potvrdnog okvira ili ponovnog spremanja zapisa. Mala zakazana Apex klasa koja traži završene upise bez id-a awarda i s privremenom pogreškom te ih ponovno stavlja u red daje vam automatski red za ponovne pokušaje bez dodatne infrastrukture. Ograničite broj pokušaja poljem brojača kako trajno loš zapis ne bi vrtio petlju unedogled.

Provjerite svoj plan prije nego ovo povežete s produkcijom. Free plan pokriva 1.200 vjerodajnica godišnje; Starter košta $9 mjesečno, a Pro $29 mjesečno. Okidač koji se aktivira na svaki Lead brzo bi potrošio mali plan, zato kriterije ograničite na stvarna postignuća.

Kako vjerodajnicu učiniti vidljivom u Salesforceu

Kad se Badge_Url__c popuni, možete ga koristiti bilo gdje:

• Obavijesti i predlošci e-pošte: spojite polje u e-poruku «Čestitamo, evo vaše vjerodajnice».
• Izvješća: izvješće na Badge_Award_Id__c != null daje vam broj izdanih vjerodajnica po tečaju, regiji ili vlasniku računa.
• Experience Cloud: prikažite poveznicu na partnerskoj stranici certifikacije kako bi kupci mogli sami provjeriti.
• Page layouti: dodajte polje URL kako bi podrška na prvi pogled mogla odgovoriti na pitanje «je li dobila svoju značku?».

Stranica za provjeru je javna i ne traži registraciju, u tome je cijela poanta. Primatelj, voditelj zapošljavanja ili nabavni tim klijenta može otvoriti poveznicu i potvrditi tko je izdao vjerodajnicu, što ona potvrđuje i kada. Za strojno čitljive provjere, Open Badge v2.0 JSON-LD za bilo koji award dostupan je na https://api.badges.ninja/certify-badge/award/<awardId>.

Primatelji dobivaju i uobičajene dodatke: jedinstveni URL za provjeru, QR kod, A4 PDF certifikat i opciju Add to LinkedIn iz portala za primatelje, koji se prijavljuje čarobnom poveznicom umjesto lozinkom.

Zašto je ovo bolje od AppExchange dodatka za značke

Dodaci za značke na AppExchangeu obično se naplaćuju po Salesforce korisniku ili po licenci upravljanog paketa. Taj trošak raste s veličinom vašeg Salesforce tima, a ne s brojem vjerodajnica koje izdajete, pa tim za edukaciju od deset ljudi i program s deset tisuća polaznika plaćaju vrlo različito za isti rezultat.

API integracija obrće taj model. Plaćate po količini vjerodajnica na paušalnom planu, kod okidača je vaš da ga čitate i mijenjate, a izlaz je standardni Open Badge v2.0, pa primatelji nisu vezani uz vlasnički preglednik. Zadržavate i slobodu dizajna: vizualni dizajner nudi više od 80 predložaka, oblika, ikona i vlastitih prijenosa, umjesto fiksnog izgleda unutar paketa.

Iskrena protuteža: dodatak se instalira jednim klikom i ne treba Apex. Ako nitko u vašem timu ne može održavati nekoliko desetaka redaka koda, dodatak ili no-code konektor može biti bolji izbor. Ako općenito uspoređujete platforme, a ne integracije, pregled alternative za Credly uspoređuje cijene i razlike u funkcijama jedno uz drugo.

Testiranje prije puštanja u rad

Cijeli tijek prvo pokrenite u sandboxu.

1. Izradite testnu značku i testnog primatelja s e-adresom koju kontrolirate.
2. U Apex testovima implementirajte HttpCalloutMock koji vraća status 200 i {"awardId":"test-award-id"}; Salesforce ne dopušta stvarne calloute u testnom kontekstu, a to vam pokriće treba za deployment.
3. U sandboxu postavite jedan upis na Completed i provjerite da se Badge_Award_Id__c i Badge_Url__c popune unutar minute.
4. Otvorite URL u privatnom prozoru preglednika kako biste potvrdili da se javna stranica za provjeru prikazuje bez prijave.
5. Izazovite neuspjeh (ostavite id značke praznim ili upotrijebite ime primatelja kraće od pet znakova) i potvrdite da pogreška završi u Badge_Error__c.

Rotirajte API ključ ako ikad procuri u debug log ili snimku zaslona. Opoziv je trenutačan sa stranice API Keys, a ažurirati treba samo External Credential, ne vaš kod.

Zaključak

Obrazac je malen: tanki okidač odlučuje kada, Queueable obavlja callout, Named Credential drži ključ, a tri polja na zapisu pohranjuju ishod. Radi za edukacijske miljokaze, partnerske razine, prisustvo na događajima ili bilo koju promjenu stanja koju možete izraziti u Salesforceu.

Počnite s jednim objektom i jednom značkom, pratite ga tjedan dana i proširite kad vam ponašanje ponovnih pokušaja odgovara za vaše podatke.

Spremni izdati svoju prvu provjerljivu vjerodajnicu? Počnite besplatno na badges.ninja — vizualni dizajner, javna stranica za provjeru, PDF certifikat, Open Badge v2.0 izlaz. Kreditna kartica nije potrebna.