Salesforce Open Badges: vydávanie overiteľných poverení z CRM triggerov

Väčšina školiacich tímov už eviduje v Salesforce, kto čo dokončil. Zápis na kurz prejde do stavu „Completed“, partnerský účet dosiahne úroveň certifikácie, zákazník dokončí onboarding. Záznam sa zmení a o týždeň neskôr niekto exportuje zoznam a certifikáty rozosiela ručne e-mailom.

Táto príručka ukazuje, ako túto medzeru zacelíte: keď záznam dosiahne stav, na ktorom vám záleží, Salesforce zavolá API https://badges.ninja, vydá sa poverenie Open Badge v2.0 a odkaz na overenie sa uloží späť do záznamu. Tento odkaz potom môžete vložiť do e-mailovej šablóny, reportu alebo stránky v Experience Cloud.

Budete potrebovať správcu Salesforce (alebo developer sandbox), odznak, ktorý je už navrhnutý na https://badges.ninja, a API kľúč. Ak ste API ešte nikdy nevolali, najprv si prečítajte rýchly štart API; zaberie desať minút.

Kedy je CRM trigger správny nástroj

Skôr než začnete písať Apex, zvážte, či ho vôbec potrebujete. Ak poverenia vydávate dávkovo raz za semester alebo štvrťrok, nahratie CSV z dashboardu je rýchlejšie a nevyžaduje žiadny kód. Cesta cez Salesforce sa oplatí, keď:

• Vydanie sa má stať v okamihu zmeny záznamu, bez ľudského kroku.
• Údaje o tom, kto čo získal, už žijú v Salesforce a nechcete druhý zdroj pravdy.
• Chcete mať odkaz na poverenie uložený na Contact, Lead alebo vlastnom školiacom zázname kvôli reportingu.

Ak je vaším nástrojom na workflow Zapier a nie Apex, rovnaké volanie API funguje aj tam; pozrite si automatizáciu Open Badges cez Zapier.

Čo budete budovať

Tok má štyri časti:

1. Odznak navrhnutý vo vizuálnom designéri. Skopírujte jeho id (pole id vrátené z GET /badges).
2. API kľúč vytvorený na stránke API Keys vo vašom dashboarde. Kľúč sa zobrazí iba raz, preto si ho hneď uložte.
3. Named Credential v Salesforce, ktorý kľúč uchováva, aby sa nikdy neobjavil v kóde.
4. Apex trigger plus trieda Queueable, ktorá vydá ocenenie a zapíše odkaz naň späť do záznamu.

Krok 1: Uložte kľúč do Named Credential

Pevne zakódovaný API kľúč v Apexe je chyba, ktorej sa treba vyhnúť. V Setup vytvorte External Credential s vlastnou hlavičkou a potom Named Credential, ktorý ukazuje na hostiteľa API:

• URL: https://api.badges.ninja
• Názov vlastnej hlavičky: X-Api-Key
• Hodnota vlastnej hlavičky: váš kľúč v tvare bws_YOUR_KEY_HERE
• Názov Named Credential: BadgesNinja

Udeľte permission setu, ktorý spúšťa vašu automatizáciu, prístup k principalu External Credential. Ak existuje Named Credential, samostatné Remote Site Setting nepotrebujete; Salesforce autorizuje callout cez credential. Ak vaša org stále používa staršie Named Credentials alebo obyčajný endpoint, pridajte https://api.badges.ninja ako Remote Site Setting a hlavičku posielajte z kódu.

Krok 2: Pridajte polia do záznamu

Na objekt, ktorý predstavuje úspech (použijeme vlastný objekt Training_Enrollment__c), pridajte:

• Badge_Id__c (Text): odznak, ktorý sa má vydať. Ak ho ukladáte pre každý kurz, jeden trigger obslúži veľa odznakov.
• Badge_Award_Id__c (Text, unique): id ocenenia vrátené z API.
• Badge_Url__c (URL): verejná stránka na overenie.
• Badge_Error__c (Long Text): posledná chyba, aby správcovia videli zlyhania bez otvárania debug logov.

Pole Badge_Award_Id__c plní dvojitú úlohu. Je to vaša ochrana pred duplicitami: trigger vydáva, len keď je prázdne.

Krok 3: Apex callout

Trigger nemôže robiť callout priamo, pretože callouty nie sú povolené v tej istej transakcii s nepotvrdeným DML. Prácu odovzdajte triede Queueable, ktorá implementuje Database.AllowsCallouts.

Kontrakt API pre POST /awards je krátky. Telo obsahuje badgeId, vnorený objekt recipient s name a email a povinné issuedOn. Úspešné volanie vráti HTTP 200 s { "awardId": "..." }. Meno príjemcu musí mať aspoň päť znakov, takže Contact s menom „Al Li“ bude zamietnutý; pred volaním validujte.

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 detaily, ktoré stoja za povšimnutie. Po prvé, issuedOn je epoch v milisekundách, presne to, čo vracia Datetime.getTime(). Po druhé, odpoveď neobsahuje URL na overenie, preto ho kód zostaví z id ocenenia: https://badges.ninja/awards/<awardId>.

Krok 4: Trigger

Trigger nechajte tenký. Iba rozhoduje, ktoré záznamy vyhovujú, a zaradí do fronty jednu úlohu na záznam.

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

Kontrola wasCompleted je dôležitá. Bez nej by každá neskoršia úprava dokončeného záznamu spustila logiku znova. Spolu so strážou prázdneho award id vnútri úlohy môže záznam vyprodukovať vždy len jedno poverenie.

Jedno obmedzenie, ktoré treba rešpektovať: Salesforce umožňuje zaradiť z jednej transakcie do fronty len malý počet úloh Queueable (50 v synchrónnom kontexte). Ak hromadne nahrávate dokončenia, povedzme import 2 000 riadkov, uvedený trigger tento strop dosiahne. Pri hromadných nahrávaniach buď nahrajte zoznam cez hromadné ocenenia z CSV v dashboarde, alebo prejdite na triedu Batchable s Database.AllowsCallouts, ktorá spracúva niekoľko záznamov na jeden scope.

Spracovanie chýb a opakované pokusy

API vracia štandardné stavové kódy a každý si od vášho kódu žiada inú reakciu:

Keďže úloha zapíše chybu do záznamu a nechá Badge_Award_Id__c prázdne, opakovanie je také jednoduché ako prepnutie checkboxu alebo opätovné uloženie záznamu. Malá plánovaná trieda Apex, ktorá hľadá dokončené zápisy bez award id a s prechodnou chybou a znova ich zaradí do fronty, vám dá automatickú frontu opakovaní bez ďalšej infraštruktúry. Počet pokusov obmedzte poľom-počítadlom, aby trvalo chybný záznam nekrúžil donekonečna.

Pred nasadením do produkcie skontrolujte svoj plán. Plán Free pokrýva 1 200 poverení ročne; Starter stojí $9 mesačne a Pro $29 mesačne. Trigger, ktorý sa spustí na každý Lead, by malý plán rýchlo vyčerpal, preto kritériá zúžte na skutočné úspechy.

Ako poverenie zviditeľniť v Salesforce

Keď je Badge_Url__c vyplnené, môžete ho použiť kdekoľvek:

• E-mailové upozornenia a šablóny: zlúčte pole do e-mailu „Gratulujeme, tu je vaše poverenie“.
• Reporty: report nad Badge_Award_Id__c != null vám dá počty vydaní podľa kurzu, regiónu alebo vlastníka účtu.
• Experience Cloud: zobrazte odkaz na stránke certifikácie partnera, aby si ho kupujúci mohli overiť sami.
• Page layouts: pridajte pole URL, aby podpora mohla na otázku „dostala svoj odznak?“ odpovedať jediným pohľadom.

Stránka na overenie je verejná a nevyžaduje registráciu, v čom je celý zmysel. Príjemca, personalista či obstarávací tím zákazníka môže otvoriť odkaz a potvrdiť, kto poverenie vydal, čo osvedčuje a kedy. Pre strojovo čitateľné kontroly je Open Badge v2.0 JSON-LD pre akékoľvek ocenenie dostupný na https://api.badges.ninja/certify-badge/award/<awardId>.

Príjemcovia dostanú aj obvyklé bonusy: jedinečnú URL na overenie, QR kód, PDF certifikát vo formáte A4 a možnosť Add to LinkedIn z portálu pre príjemcov, ktorý sa prihlasuje magic linkom namiesto hesla.

Prečo je to lepšie ako plugin s odznakmi z AppExchange

Pluginy s odznakmi na AppExchange sa zvyčajne oceňujú na používateľa Salesforce alebo na licenciu managed balíka. Táto cena rastie s veľkosťou vášho tímu v Salesforce, nie s počtom vydaných poverení, takže desaťčlenný školiaci tím a program s desaťtisíc študentmi platia za rovnaký výstup veľmi odlišne.

Integrácia cez API tento model obracia. Platíte podľa objemu poverení v paušálnom pláne, kód triggera si môžete čítať a meniť a výstup je štandardný Open Badge v2.0, takže príjemcovia nie sú uzamknutí v proprietárnom prehliadači. Zachovávate si aj slobodu dizajnu: vizuálny designér ponúka 80+ šablón, tvarov, ikon a vlastných nahraní namiesto pevného rozloženia v balíku.

Úprimný kompromis: plugin sa inštaluje kliknutím a nepotrebuje Apex. Ak nikto vo vašom tíme nevie udržiavať pár desiatok riadkov kódu, môže byť vhodnejší plugin alebo no-code konektor. Ak porovnávate platformy vo všeobecnosti a nie integrácie, prehľad alternatíva ku Credly porovnáva ceny a rozdiely vo funkciách vedľa seba.

Testovanie pred ostrým nasadením

Celý tok si najprv vyskúšajte v sandboxe.

1. Vytvorte testovací odznak a testovacieho príjemcu s e-mailovou adresou, ktorú ovládate.
2. V testoch Apex implementujte HttpCalloutMock, ktorý vráti stav 200 a {"awardId":"test-award-id"}; Salesforce v testovacom kontexte nepovoľuje skutočné callouty a toto pokrytie potrebujete na nasadenie.
3. V sandboxe nastavte jeden zápis na Completed a skontrolujte, či sa Badge_Award_Id__c a Badge_Url__c vyplnia do minúty.
4. Otvorte URL v súkromnom okne prehliadača a overte, že sa verejná stránka na overenie zobrazí bez prihlásenia.
5. Vynúťte zlyhanie (vymažte id odznaku alebo použite meno príjemcu kratšie ako päť znakov) a potvrďte, že chyba skončí v Badge_Error__c.

API kľúč vymeňte, ak by niekedy unikol do debug logu alebo screenshotu. Zrušenie je okamžité zo stránky API Keys a aktualizovať stačí External Credential, nie váš kód.

Zhrnutie

Vzor je malý: tenký trigger rozhoduje kedy, Queueable robí callout, Named Credential uchováva kľúč a tri polia v zázname ukladajú výsledok. Funguje pre školiace míľniky, partnerské úrovne, účasť na podujatiach alebo akúkoľvek zmenu stavu, ktorú viete vyjadriť v Salesforce.

Začnite s jedným objektom a jedným odznakom, sledujte ho týždeň a rozširujte, keď vám správanie opakovaní vyhovuje pre vaše dáta.

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