Salesforce Open Badges: vydávání ověřitelných certifikátů z triggerů CRM

Většina školicích týmů už v Salesforce eviduje, kdo co dokončil. Přihláška na kurz přejde do stavu „Completed”, partnerský účet dosáhne certifikační úrovně, zákazník dokončí onboarding. Záznam se změní a o týden později někdo exportuje seznam a certifikáty rozesílá ručně e-mailem.

Tento návod ukazuje, jak tuto mezeru zacelit: když záznam dosáhne stavu, na kterém vám záleží, Salesforce zavolá API https://badges.ninja, vydá se certifikát Open Badge v2.0 a ověřovací odkaz se uloží zpět do záznamu. Ten odkaz pak můžete vložit do šablony e-mailu, reportu nebo stránky Experience Cloud.

Budete potřebovat správce Salesforce (nebo vývojářský sandbox), odznak již navržený na https://badges.ninja a klíč API. Pokud jste API ještě nikdy nevolali, přečtěte si nejdřív rychlý start API; zabere deset minut.

Kdy je trigger CRM správný nástroj

Než začnete psát Apex, zjistěte, jestli ho vůbec potřebujete. Pokud certifikáty vydáváte dávkově jednou za semestr nebo čtvrtletí, je nahrání CSV v panelu rychlejší a nepotřebuje žádný kód. Cesta přes Salesforce se vyplatí, když:

• Vydání má proběhnout ve chvíli změny záznamu, bez lidského zásahu.
• Data o tom, „kdo to získal”, už jsou v Salesforce a nechcete druhý zdroj pravdy.
• Chcete mít odkaz na certifikát uložený u Contact, Lead nebo vlastního školicího záznamu pro účely reportingu.

Pokud je vaším nástrojem Zapier místo Apexu, stejné volání API funguje i tam; viz automatizace Open Badges v Zapieru.

Co budujete

Tok má čtyři části:

1. Odznak navržený ve vizuálním designéru. Zkopírujte jeho id (pole id vracené z GET /badges).
2. Klíč API vytvořený na stránce API Keys ve vašem panelu. Klíč se zobrazí jen jednou, takže si ho hned uložte.
3. Named Credential v Salesforce, který klíč drží, takže se nikdy neobjeví v kódu.
4. Trigger Apex a třída Queueable, které vydají ocenění a odkaz na něj zapíší zpět do záznamu.

Krok 1: Uložte klíč do Named Credential

Natvrdo zapsaný klíč API v Apexu je chyba, které se vyhněte. V Setup vytvořte External Credential s vlastní hlavičkou a poté Named Credential ukazující na hostitele API:

• URL: https://api.badges.ninja
• Název vlastní hlavičky: X-Api-Key
• Hodnota vlastní hlavičky: váš klíč ve tvaru bws_YOUR_KEY_HERE
• Název Named Credential: BadgesNinja

Udělte sadě oprávnění, která vaši automatizaci spouští, přístup k principalu External Credential. Když je Named Credential na místě, nepotřebujete samostatné Remote Site Setting; Salesforce volání autorizuje přes tento certifikát. Pokud vaše organizace stále používá starší Named Credentials nebo obyčejný endpoint, přidejte https://api.badges.ninja jako Remote Site Setting a hlavičku posílejte z kódu.

Krok 2: Přidejte pole do záznamu

Na objekt, který představuje úspěch (použijeme vlastní objekt Training_Enrollment__c), přidejte:

• Badge_Id__c (Text): odznak, který se má vydat. Uložení u každého kurzu umožní jednomu triggeru obsloužit mnoho odznaků.
• Badge_Award_Id__c (Text, unique): id ocenění vrácené z API.
• Badge_Url__c (URL): veřejná ověřovací stránka.
• Badge_Error__c (Long Text): poslední chyba, aby správci viděli selhání bez otevírání ladicích logů.

Pole Badge_Award_Id__c plní dvojí úlohu. Je to vaše ochrana proti duplicitám: trigger vydává, jen když je prázdné.

Krok 3: Volání Apex

Trigger nemůže volání provést přímo, protože volání externích služeb nejsou povolena ve stejné transakci jako nepotvrzené DML. Předejte práci třídě Queueable, která implementuje Database.AllowsCallouts.

Kontrakt API pro POST /awards je krátký. Tělo nese badgeId, vnořený objekt recipient s name a email a povinné issuedOn. Úspěšné volání vrací HTTP 200 s { "awardId": "..." }. Jméno příjemce musí mít alespoň pět znaků, takže Contact s názvem „Al Li” by byl odmítnut; data před voláním ověřte.

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

Stojí za povšimnutí dva detaily. Zaprvé, issuedOn jsou epoch milisekundy, přesně to, co vrací Datetime.getTime(). Zadruhé, odpověď neobsahuje ověřovací URL, takže ji kód sestaví z id ocenění: https://badges.ninja/awards/<awardId>.

Krok 4: Trigger

Udržte trigger tenký. Jen rozhoduje, které záznamy vyhovují, a zařazuje 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 ní by každá pozdější úprava dokončeného záznamu logiku spustila znovu. Spolu s pojistkou prázdného id ocenění uvnitř úlohy může záznam vyprodukovat jen jeden certifikát.

Jeden limit je třeba respektovat: Salesforce povoluje z jedné transakce zařadit jen malý počet úloh Queueable (50 v synchronním kontextu). Pokud dokončení načítáte hromadně, řekněme importem 2000 řádků, výše uvedený trigger na tento strop narazí. U hromadných načtení buď nahrajte seznam přes hromadná ocenění CSV v panelu, nebo přejděte na třídu Batchable s Database.AllowsCallouts, která zpracuje několik záznamů na jeden rozsah.

Zpracování chyb a opakování

API vrací standardní stavové kódy a každý z nich vyžaduje jinou reakci vašeho kódu:

Protože úloha zapíše chybu do záznamu a nechá Badge_Award_Id__c prázdné, opakování je stejně jednoduché jako přepnutí zaškrtávacího políčka nebo opětovné uložení záznamu. Malá plánovaná třída Apex, která hledá dokončené přihlášky bez id ocenění s přechodnou chybou a znovu je zařazuje, vám dá automatickou frontu opakování bez další infrastruktury. Počet pokusů omezte polem s čítačem, aby se trvale vadný záznam nezacyklil.

Před nasazením do produkce zkontrolujte svůj plán. Plán Free pokrývá 1200 certifikátů ročně; Starter stojí $9 měsíčně a Pro $29 měsíčně. Trigger spouštěný na každém Lead by malý plán rychle vyčerpal, takže kritéria omezte na skutečné úspěchy.

Jak certifikát zviditelnit v Salesforce

Jakmile je Badge_Url__c vyplněno, můžete ho použít kdekoli:

• E-mailová upozornění a šablony: vložte pole do e-mailu „Gratulujeme, tady je váš certifikát”.
• Reporty: report na Badge_Award_Id__c != null vám dá počty vydání podle kurzu, regionu nebo vlastníka účtu.
• Experience Cloud: zobrazte odkaz na certifikační stránce partnera, aby si ho kupující mohli sami ověřit.
• Rozvržení stránek: přidejte pole URL, aby podpora mohla odpovědět na otázku „dostala svůj odznak?” jedním pohledem.

Ověřovací stránka je veřejná a nevyžaduje registraci, což je celý smysl. Příjemce, náborář nebo nákupní oddělení zákazníka může odkaz otevřít a potvrdit, kdo certifikát vydal, co osvědčuje a kdy. Pro strojové kontroly je JSON-LD Open Badge v2.0 pro každé ocenění dostupný na https://api.badges.ninja/certify-badge/award/<awardId>.

Příjemci dostávají i obvyklé bonusy: jedinečnou ověřovací URL, QR kód, PDF certifikát formátu A4 a možnost Add to LinkedIn z portálu příjemce, který se přihlašuje magickým odkazem místo hesla.

Proč je to lepší než plugin s odznaky z AppExchange

Pluginy s odznaky na AppExchange se obvykle cení za uživatelské místo Salesforce nebo za licenci spravovaného balíčku. Tato cena roste s velikostí vašeho týmu Salesforce, ne s počtem vydaných certifikátů, takže desetičlenný školicí tým a program s deseti tisíci studenty platí za stejný výstup zcela odlišně.

Integrace přes API tento model obrací. Platíte podle objemu certifikátů v paušálním plánu, kód triggeru si můžete číst i měnit a výstupem je standardní Open Badge v2.0, takže příjemci nejsou uzamčeni v proprietárním prohlížeči. Zachováváte si také designovou svobodu: vizuální designér nabízí více než 80 šablon, tvarů, ikon a vlastní nahrávání místo pevného rozvržení uvnitř balíčku.

Upřímný kompromis: plugin se instaluje jedním kliknutím a nepotřebuje Apex. Pokud nikdo ve vašem týmu nezvládne udržovat několik desítek řádků kódu, může být lepší volbou plugin nebo no-code konektor. Pokud srovnáváte platformy obecně, ne integrace, přehled alternativy ke Credly srovnává ceny a funkce vedle sebe.

Testování před spuštěním

Celý tok nejprve vyzkoušejte v sandboxu.

1. Vytvořte testovací odznak a testovacího příjemce s e-mailovou adresou, kterou ovládáte.
2. V testech Apex implementujte HttpCalloutMock vracející stav 200 a {"awardId":"test-award-id"}; Salesforce v testovacím kontextu skutečná volání nepovolí a toto pokrytí potřebujete k nasazení.
3. V sandboxu nastavte jednu přihlášku na Completed a ověřte, že se Badge_Award_Id__c a Badge_Url__c vyplní do minuty.
4. Otevřete URL v anonymním okně prohlížeče a ověřte, že se veřejná ověřovací stránka zobrazí bez přihlášení.
5. Vynuťte selhání (smažte id odznaku nebo použijte jméno příjemce kratší než pět znaků) a potvrďte, že chyba skončí v Badge_Error__c.

Klíč API vyměňte, pokud kdy unikne do ladicího logu nebo snímku obrazovky. Zneplatnění je okamžité na stránce API Keys a aktualizovat stačí External Credential, ne váš kód.

Závěrem

Vzor je malý: tenký trigger rozhoduje kdy, Queueable provede volání, Named Credential drží klíč a tři pole v záznamu uchovávají výsledek. Funguje pro školicí milníky, partnerské úrovně, účast na akcích i jakoukoli změnu stavu, kterou lze v Salesforce vyjádřit.

Začněte s jedním objektem a jedním odznakem, týden ho sledujte a rozšiřte ho, až vám chování opakování vyhovuje.

Chcete vydat svůj první ověřitelný certifikát? Začněte zdarma na badges.ninja — vizuální designér, veřejná ověřovací stránka, PDF certifikát, výstup Open Badge v2.0. Kreditní karta není potřeba.