Salesforce Open Badges: kontrollitavate volituste väljaandmine CRM-i päästikutest

Enamik koolitusmeeskondi märgib juba Salesforce’is üles, kes mille lõpetas. Kursusele registreerumine liigub staatusesse „Completed“, partnerikonto jõuab sertifitseerimistasemele, klient lõpetab sisseelamise. Kirje muutub ja siis ekspordib keegi nädal hiljem nimekirja ning saadab sertifikaadid käsitsi e-postiga.

See juhend näitab, kuidas see lünk sulgeda: kui kirje jõuab sinu jaoks olulisse staatusesse, kutsub Salesforce välja https://badges.ninja API, välja antakse Open Badge v2.0 volitus ja kontrolllink salvestatakse kirjele tagasi. Selle lingi saad seejärel panna e-posti malli, aruandesse või Experience Cloudi lehele.

Sul on vaja Salesforce’i administraatorit (või arendaja sandbox’i), https://badges.ninja keskkonnas juba kujundatud märki ja API võtit. Kui sa pole API-t varem kutsunud, loe esmalt läbi API kiirjuhend; see võtab kümme minutit.

Millal on CRM-i päästik õige tööriist

Enne Apex-i kirjutamist kontrolli, kas sul seda üldse vaja on. Kui annad volitusi välja partiidena kord semestris või kord kvartalis, on töölaua CSV-üleslaadimine kiirem ega vaja üldse koodi. Salesforce’i tee tasub end ära, kui:

• väljaandmine peab toimuma hetkel, kui kirje muutub, ilma inimsammuta.
• „kes selle välja teenis“ andmed juba asuvad Salesforce’is ja sa ei soovi teist tõeallikat.
• soovid volituse lingi aruandluse jaoks salvestada Contact’i, Lead’i või oma koolituskirje juurde.

Kui sinu töövoo tööriist on Zapier, mitte Apex, töötab sama API-päring ka seal; vaata Open Badges’i automatiseerimine Zapieriga.

Mida sa ehitad

Voos on neli osa:

1. Märk, mis on kujundatud visuaalses disainerais. Kopeeri selle id (väli id, mille tagastab GET /badges).
2. API võti, mis on loodud sinu töölaua lehel API Keys. Võtit näidatakse ainult üks kord, nii et salvesta see kohe.
3. Named Credential Salesforce’is, mis hoiab võtit, nii et see ei ilmu kunagi koodis.
4. Apex-i päästik pluss Queueable-klass, mis annab auhinna välja ja kirjutab auhinna lingi kirjele tagasi.

1. samm: salvesta võti Named Credential’isse

API võtme kõvakodeerimine Apex-i on viga, mida tuleb vältida. Loo Setup’is External Credential kohandatud päisega ja seejärel Named Credential, mis osutab API hostile:

• URL: https://api.badges.ninja
• Kohandatud päise nimi: X-Api-Key
• Kohandatud päise väärtus: sinu võti kujul bws_YOUR_KEY_HERE
• Named Credential’i nimi: BadgesNinja

Anna sinu automatiseeringut käitavale õiguste komplektile juurdepääs External Credential’i põhiosapoolele (principal). Named Credential’i olemasolul ei vaja sa eraldi Remote Site Setting’ut; Salesforce autoriseerib päringu volituse kaudu. Kui sinu organisatsioon kasutab veel vanemat tüüpi Named Credential’eid või lihtsat lõpp-punkti, lisa https://api.badges.ninja Remote Site Setting’uks ja saada päis koodist.

2. samm: lisa kirjele väljad

Objektile, mis esindab saavutust (kasutame kohandatud objekti Training_Enrollment__c), lisa:

• Badge_Id__c (Text): väljaantav märk. Kursuse kohta salvestatuna saab üks päästik teenindada paljusid märke.
• Badge_Award_Id__c (Text, unique): API tagastatud auhinna id.
• Badge_Url__c (URL): avalik kontrollileht.
• Badge_Error__c (Long Text): viimane viga, et administraatorid näeksid tõrkeid ilma silumislogisid avamata.

Väli Badge_Award_Id__c täidab kahte rolli. See on sinu duplikaadikaitse: päästik annab välja ainult siis, kui see on tühi.

3. samm: Apex-i päring

Päästik ei saa päringut otse teha, sest päringud pole lubatud samas tehingus kinnitamata DML-iga. Anna töö üle Queueable’ile, mis implementeerib Database.AllowsCallouts.

POST /awards API leping on lühike. Keha sisaldab badgeId, pesastatud recipient objekti väljadega name ja email ning kohustuslikku issuedOn. Edukas päring tagastab HTTP 200 ja { "awardId": "..." }. Saaja nimi peab olema vähemalt viis tähemärki, seega lükataks Contact nimega „Al Li“ tagasi; valideeri enne päringut.

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

Kaks tähelepanuväärset detaili. Esiteks, issuedOn on epohhi millisekundid, täpselt see, mida Datetime.getTime() tagastab. Teiseks, vastus ei sisalda kontrolli URL-i, nii et kood koostab selle auhinna id-st: https://badges.ninja/awards/<awardId>.

4. samm: päästik

Hoia päästik õhuke. See otsustab ainult, millised kirjed sobivad, ja paneb iga kirje kohta järjekorda ühe töö.

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

Kontroll wasCompleted on oluline. Ilma selleta käivitaks iga hilisem lõpetatud kirje muutmine loogika uuesti. Koos töö sees oleva tühja auhinna id kaitsega saab kirje anda alati ainult ühe volituse.

Üks piirang, mida järgida: Salesforce lubab ühest tehingust järjekorda panna väikese arvu Queueable-töid (sünkroonses kontekstis 50). Kui laed lõpetamisi hulgi, näiteks 2000-realise andmeimpordiga, jõuab ülaltoodud päästik selle piirini. Hulgilaadimiste jaoks lae nimekiri üles hoopis töölaua CSV hulgiauhindade kaudu või vaheta Batchable-klassi vastu, millel on Database.AllowsCallouts ja mis töötleb ühe skoobi kohta mõne kirje.

Veakäsitlus ja kordusüritused

API tagastab standardseid olekukoode ning iga kood nõuab sinu koodilt erinevat reaktsiooni:

Kuna töö kirjutab vea kirjele ja jätab Badge_Award_Id__c tühjaks, on kordusüritus sama lihtne kui märkeruudu ümberlülitamine või kirje uuesti salvestamine. Väike ajastatud Apex-i klass, mis otsib lõpetatud registreeringuid, millel pole auhinna id-d ja mille viga on ajutine, ning paneb need uuesti järjekorda, annab sulle automaatse kordusjärjekorra ilma lisataristuta. Piira katseid loenduriväljaga, et püsivalt vigane kirje ei jääks lõputult tsüklisse.

Kontrolli oma paketti enne, kui selle tootmisega ühendad. Free pakett katab 1200 volitust aastas; Starter maksab 9 $ kuus ja Pro 29 $ kuus. Päästik, mis käivitub iga Lead’i peal, tarbiks väikese paketi kiiresti ära, seega piira kriteeriumid päris saavutustega.

Volituse nähtavaks tegemine Salesforce’is

Kui Badge_Url__c on täidetud, saad seda kasutada kõikjal:

• E-posti teavitused ja mallid: põimi väli e-kirja „Palju õnne, siin on sinu volitus“.
• Aruanded: aruanne tingimusel Badge_Award_Id__c != null annab väljaandmiste arvu kursuse, piirkonna või konto omaniku kaupa.
• Experience Cloud: näita linki partneri sertifitseerimislehel, et ostjad saaksid selle ise kontrollida.
• Lehepaigutused: lisa URL-i väli, et tugitöötajad saaksid küsimusele „kas ta sai oma märgi kätte?“ vastata ühe pilguga.

Kontrollileht on avalik ega nõua registreerumist, selles ongi kogu point. Saaja, värbaja või kliendi hankemeeskond saab avada lingi ja kinnitada, kes volituse välja andis, mida see tõendab ja millal. Masinloetavate kontrollide jaoks on mis tahes auhinna Open Badge v2.0 JSON-LD saadaval aadressil https://api.badges.ninja/certify-badge/award/<awardId>.

Saajad saavad ka tavapärased lisad: unikaalse kontrolli URL-i, QR-koodi, A4 PDF-sertifikaadi ja Add to LinkedIn võimaluse saajaportaalis, kuhu logitakse sisse võlulingiga, mitte parooliga.

Miks see on parem kui AppExchange’i märkide plugin

AppExchange’i märkide pluginad on tavaliselt hinnastatud Salesforce’i kasutaja või hallatava paketi litsentsi kaupa. See kulu kasvab sinu Salesforce’i meeskonna suurusega, mitte väljaantud volituste arvuga, nii et kümneliikmeline koolitusmeeskond ja kümne tuhande õppijaga programm maksavad sama tulemuse eest väga erinevalt.

API-integratsioon pöörab selle mudeli ümber. Maksad volituste mahu järgi fikseeritud paketiga, päästiku kood on sinu päralt, et seda lugeda ja muuta, ning väljund on standardne Open Badge v2.0, nii et saajad pole suletud ühtegi patenteeritud vaaturisse. Säilitad ka disainivabaduse: visuaalne disainer pakub 80+ malli, kujundit, ikooni ja kohandatud üleslaadimist, mitte paketisisest fikseeritud paigutust.

Aus kompromiss: plugin installitakse ühe klõpsuga ega vaja Apex-it. Kui keegi sinu meeskonnas ei suuda hooldada paari tosinat koodirida, võib plugin või koodita konnektor olla parem valik. Kui võrdled üldiselt platvorme, mitte integratsioone, käsitleb Credly alternatiiv hinna- ja funktsioonierinevusi kõrvuti.

Testimine enne tootmisse minekut

Käivita kogu voog esmalt sandbox’is.

1. Loo testmärk ja testsaaja e-posti aadressiga, mida sa kontrollid.
2. Apex-i testides implementeeri HttpCalloutMock, mis tagastab oleku 200 ja {"awardId":"test-award-id"}; Salesforce ei luba testikontekstis päris päringuid ja sul on seda katvust juurutamiseks vaja.
3. Sandbox’is sea üks registreering olekusse Completed ja kontrolli, et Badge_Award_Id__c ja Badge_Url__c täituvad minuti jooksul.
4. Ava URL privaatses brauseriaknas, et kinnitada, et avalik kontrollileht kuvatakse ilma sisselogimata.
5. Põhjusta tõrge (tühjenda märgi id või kasuta alla viie tähemärgi pikkust saaja nime) ja kinnita, et viga jõuab Badge_Error__c välja.

Roteeri API võti, kui see peaks silumislogisse või ekraanipilti sattuma. Tühistamine on API Keys lehel kohene ja sul tuleb uuendada ainult External Credential, mitte oma koodi.

Kokkuvõte

Muster on väike: õhuke päästik otsustab, millal, Queueable teeb päringu, Named Credential hoiab võtit ja kolm kirje välja salvestavad tulemuse. See sobib koolituse verstapostidele, partnerite tasemetele, ürituste külastatavusele või mis tahes olekumuutusele, mida saad Salesforce’is väljendada.

Alusta ühe objekti ja ühe märgiga, jälgi seda nädal aega ja laienda, kui kordusüritamise käitumine sinu andmetele sobib.

Valmis andma välja oma esimest kontrollitavat volitust? Alusta tasuta badges.ninjas — visuaalne disainer, avalik kontrollileht, PDF-sertifikaat, Open Badge v2.0 väljund. Krediitkaart pole vajalik.