Salesforce Open Badges: izdajanje preverljivih poverilnic iz sprožilcev CRM

Večina ekip za usposabljanje že beleži, kdo je kaj opravil, v Salesforceu. Vpis na tečaj preide v stanje »Completed«, partnerski račun doseže certifikacijsko stopnjo, stranka konča uvajanje. Zapis se spremeni, nato pa nekdo teden dni kasneje izvozi seznam in certifikate pošlje ročno po e-pošti.

Ta vodnik pokaže, kako zapolniti to vrzel: ko zapis doseže stanje, ki vas zanima, Salesforce pokliče API https://badges.ninja, izda se poverilnica Open Badge v2.0, povezava za preverjanje pa se shrani nazaj v zapis. To povezavo nato vstavite v predlogo e-pošte, poročilo ali stran Experience Cloud.

Potrebovali boste Salesforce skrbnika (ali razvijalski sandbox), značko, ki je na https://badges.ninja že oblikovana, in API ključ. Če API še nikoli niste klicali, najprej preberite hitri začetek z API-jem; vzame deset minut.

Kdaj je sprožilec CRM pravo orodje

Preden napišete Apex, preverite, ali ga sploh potrebujete. Če poverilnice izdajate v serijah enkrat na semester ali četrtletje, je nalaganje CSV na nadzorni plošči hitrejše in ne zahteva nobene kode. Pot prek Salesforcea se izplača, ko:

• se mora izdaja zgoditi v trenutku, ko se zapis spremeni, brez človeškega koraka.
• podatki o tem, »kdo si je to prislužil«, že živijo v Salesforceu in ne želite drugega vira resnice.
• želite povezavo do poverilnice shraniti v zapis Contact, Lead ali v lasten zapis usposabljanja zaradi poročanja.

Če je vaše orodje za poteke dela Zapier in ne Apex, deluje isti klic API-ja tudi tam; glejte avtomatizacija Open Badges z Zapierjem.

Kaj gradite

Potek ima štiri dele:

1. Značka, oblikovana v vizualnem oblikovalniku. Kopirajte njen id (polje id, ki ga vrne GET /badges).
2. API ključ, ustvarjen na strani API Keys vaše nadzorne plošče. Ključ je prikazan samo enkrat, zato ga takoj shranite.
3. Named Credential v Salesforceu, ki hrani ključ, da se nikoli ne pojavi v kodi.
4. Apex sprožilec in razred Queueable, ki izdata nagrado in povezavo do nje zapišeta nazaj v zapis.

1. korak: shranite ključ v Named Credential

API ključa nikoli ne vpisujte neposredno v Apex — to je napaka, ki se ji morate izogniti. V Setup ustvarite External Credential z lastno glavo, nato pa še Named Credential, ki kaže na gostitelja API-ja:

• URL: https://api.badges.ninja
• Ime lastne glave: X-Api-Key
• Vrednost lastne glave: vaš ključ v obliki bws_YOUR_KEY_HERE
• Ime Named Credential: BadgesNinja

Naboru dovoljenj, ki izvaja vašo avtomatizacijo, dodelite dostop do principala External Credential. Z Named Credential ne potrebujete ločene nastavitve Remote Site Setting; Salesforce klic odobri prek poverilnice. Če vaša organizacija še uporablja starejše Named Credentials ali navaden endpoint, dodajte https://api.badges.ninja kot Remote Site Setting, glavo pa pošljite iz kode.

2. korak: dodajte polja v zapis

Na objektu, ki predstavlja dosežek (uporabili bomo lasten objekt Training_Enrollment__c), dodajte:

• Badge_Id__c (Text): značka, ki jo je treba izdati. Če jo shranite pri vsakem tečaju, en sprožilec služi mnogim značkam.
• Badge_Award_Id__c (Text, unique): id nagrade, ki ga vrne API.
• Badge_Url__c (URL): javna stran za preverjanje.
• Badge_Error__c (Long Text): zadnja napaka, da skrbniki vidijo napake, ne da bi odpirali razhroščevalne dnevnike.

Polje Badge_Award_Id__c opravlja dvojno nalogo. Je vaša zaščita pred dvojniki: sprožilec izda samo, če je prazno.

3. korak: Apex klic

Sprožilec ne more neposredno izvesti klica, ker klici niso dovoljeni v isti transakciji z nepotrjenim DML. Delo predajte razredu Queueable, ki implementira Database.AllowsCallouts.

Pogodba API-ja za POST /awards je kratka. Telo vsebuje badgeId, ugnezden objekt recipient z name in email ter obvezen issuedOn. Uspešen klic vrne HTTP 200 z { "awardId": "..." }. Ime prejemnika mora imeti vsaj pet znakov, zato bi bil Contact z imenom »Al Li« zavrnjen; pred klicem preverite podatke.

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

Dve podrobnosti, vredni pozornosti. Prvič, issuedOn je epoha v milisekundah, kar je natanko to, kar vrne Datetime.getTime(). Drugič, odgovor ne vsebuje URL-ja za preverjanje, zato ga koda sestavi iz id-ja nagrade: https://badges.ninja/awards/<awardId>.

4. korak: sprožilec

Sprožilec naj bo tanek. Samo odloči, kateri zapisi ustrezajo, in v čakalno vrsto doda eno opravilo na zapis.

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

Preverjanje wasCompleted je pomembno. Brez njega bi vsako poznejše urejanje dokončanega zapisa ponovno sprožilo logiko. Skupaj s zaščito praznega id-ja nagrade v opravilu lahko zapis ustvari samo eno poverilnico.

Ena omejitev, ki jo morate spoštovati: Salesforce dovoljuje majhno število opravil Queueable, dodanih v čakalno vrsto iz ene transakcije (50 v sinhronem kontekstu). Če dokončanja nalagate v velikem obsegu, recimo z uvozom 2.000 vrstic, bo zgornji sprožilec dosegel to mejo. Pri množičnih nalaganjih seznam raje naložite prek množičnih nagrad s CSV na nadzorni plošči ali pa preklopite na razred Batchable z Database.AllowsCallouts, ki obdela nekaj zapisov na obseg.

Obravnava napak in ponovni poskusi

API vrača standardne statusne kode, vsaka pa zahteva drugačen odziv vaše kode:

Ker opravilo napako zapiše v zapis in pusti Badge_Award_Id__c prazno, je ponovni poskus tako preprost kot preklop potrditvenega polja ali ponovno shranjevanje zapisa. Majhen razporejeni razred Apex, ki poišče dokončane vpise brez id-ja nagrade s prehodno napako in jih znova doda v čakalno vrsto, vam brez dodatne infrastrukture da samodejno vrsto za ponovne poskuse. Število poskusov omejite s poljem-števcem, da trajno slab zapis ne kroži v neskončnost.

Preden to povežete s produkcijo, preverite svoj paket. Paket Free pokriva 1.200 poverilnic na leto; Starter stane 9 $ na mesec, Pro pa 29 $ na mesec. Sprožilec, ki se sproži ob vsakem Leadu, bi majhen paket hitro porabil, zato merila omejite na resnične dosežke.

Poverilnica, vidna v Salesforceu

Ko je Badge_Url__c izpolnjen, ga lahko uporabite kjer koli:

• E-poštna obvestila in predloge: polje vstavite v e-pošto »Čestitamo, tukaj je vaša poverilnica«.
• Poročila: poročilo o Badge_Award_Id__c != null vam da število izdaj po tečaju, regiji ali lastniku računa.
• Experience Cloud: povezavo prikažite na partnerjevi certifikacijski strani, da jo lahko kupci preverijo sami.
• Postavitve strani: dodajte polje URL, da lahko podpora na prvi pogled odgovori na vprašanje »ali je dobila svojo značko?«.

Stran za preverjanje je javna in ne zahteva registracije, v tem je bistvo. Prejemnik, delodajalec ali nabavna ekipa stranke lahko odpre povezavo in potrdi, kdo je poverilnico izdal, kaj potrjuje in kdaj. Za strojno berljiva preverjanja je Open Badge v2.0 JSON-LD za vsako nagrado na voljo na https://api.badges.ninja/certify-badge/award/<awardId>.

Prejemniki dobijo tudi običajne dodatke: edinstven URL za preverjanje, kodo QR, certifikat PDF v formatu A4 in možnost Add to LinkedIn iz portala za prejemnike, v katerega se prijavijo s čarobno povezavo in ne z geslom.

Zakaj je to boljše od vtičnika za značke na AppExchange

Vtičniki za značke na AppExchange so običajno cenjeni po Salesforce uporabniku ali po licenci upravljanega paketa. Ta strošek raste z velikostjo vaše Salesforce ekipe, ne s številom izdanih poverilnic, zato desetčlanska ekipa za usposabljanje in program z desettisoč učenci za enak rezultat plačata zelo različno.

Integracija prek API-ja ta model obrne. Plačate po obsegu poverilnic v fiksnem paketu, koda sprožilca je vaša, da jo berete in spreminjate, izhod pa je standardni Open Badge v2.0, zato prejemniki niso ujeti v lastniški pregledovalnik. Ohranite tudi oblikovalsko svobodo: vizualni oblikovalnik ponuja več kot 80 predlog, oblik, ikon in lastnih nalaganj, ne pa fiksne postavitve znotraj paketa.

Pošteno nasprotje: vtičnik se namesti z enim klikom in ne potrebuje Apex. Če v vaši ekipi nihče ne more vzdrževati nekaj deset vrstic kode, je lahko vtičnik ali konektor brez kode boljša izbira. Če primerjate platforme na splošno in ne integracij, alternativa Credlyju obravnava razlike v cenah in funkcijah vzporedno.

Testiranje pred zagonom

Cel potek najprej preizkusite v sandboxu.

1. Ustvarite testno značko in testnega prejemnika z e-poštnim naslovom, ki ga nadzirate.
2. V Apex testih implementirajte HttpCalloutMock, ki vrne status 200 in {"awardId":"test-award-id"}; Salesforce v testnem kontekstu ne dovoli pravih klicev, to pokritost pa potrebujete za razmestitev.
3. V sandboxu nastavite en vpis na Completed in preverite, da se Badge_Award_Id__c in Badge_Url__c izpolnita v eni minuti.
4. Odprite URL v zasebnem oknu brskalnika in potrdite, da se javna stran za preverjanje prikaže brez prijave.
5. Izzovite napako (izpraznite id značke ali uporabite ime prejemnika, krajše od petih znakov) in potrdite, da napaka pristane v Badge_Error__c.

Ključ API zamenjajte, če kdaj pricuri v razhroščevalni dnevnik ali posnetek zaslona. Preklic je takojšen na strani API Keys, posodobiti pa morate le External Credential, ne svoje kode.

Zaključek

Vzorec je majhen: tanek sprožilec odloči, kdaj, Queueable opravi klic, Named Credential hrani ključ, trije polji na zapisu pa shranijo izid. Deluje za mejnike v usposabljanju, partnerske stopnje, udeležbo na dogodkih ali katero koli spremembo stanja, ki jo lahko izrazite v Salesforceu.

Začnite z enim objektom in eno značko, spremljajte ju teden dni in razširite, ko vam obnašanje ponovnih poskusov ustreza za vaše podatke.

Ste pripravljeni izdati svojo prvo preverljivo poverilnico? Začnite brezplačno na badges.ninja — vizualni oblikovalnik, javna stran za preverjanje, certifikat PDF, izhod Open Badge v2.0. Kreditna kartica ni potrebna.