Salesforce Open Badges: patikrinamų skaitmeninių įgaliojimų išdavimas pagal CRM trigerius

Dauguma mokymų komandų jau fiksuoja Salesforce sistemoje, kas ką baigė. Kurso registracija pakeičiama į „Completed“, partnerio paskyra pasiekia sertifikavimo lygį, klientas baigia adaptaciją. Įrašas pasikeičia, o po savaitės kažkas eksportuoja sąrašą ir sertifikatus išsiunčia el. paštu rankiniu būdu.

Šiame vadove parodysime, kaip užpildyti šią spragą: kai įrašas pasiekia jums svarbią būseną, Salesforce iškviečia https://badges.ninja API, išduodamas Open Badge v2.0 įgaliojimas, o patikrinimo nuoroda išsaugoma atgal įraše. Tada šią nuorodą galite įdėti į el. laiško šabloną, ataskaitą ar Experience Cloud puslapį.

Jums prireiks Salesforce administratoriaus (arba kūrėjo smėlio dėžės), jau sukurto ženklelio svetainėje https://badges.ninja ir API rakto. Jei API dar niekada nekvietėte, pirmiausia perskaitykite API greito starto vadovą; tai užtruks dešimt minučių.

Kada CRM trigeris yra tinkama priemonė

Prieš rašydami Apex, patikrinkite, ar jo tikrai reikia. Jei įgaliojimus išduodate partijomis kartą per semestrą ar kartą per ketvirtį, skydelio CSV įkėlimas yra greitesnis ir visai nereikalauja kodo. Salesforce kelias atsiperka, kai:

• Išdavimas turi įvykti vos pasikeitus įrašui, be žmogaus žingsnio.
• Duomenys apie tai, kas įgijo įgaliojimą, jau yra Salesforce ir nenorite antro tiesos šaltinio.
• Norite įgaliojimo nuorodą saugoti Contact, Lead ar individualiame mokymų įraše ataskaitoms.

Jei jūsų darbo eigos įrankis yra Zapier, o ne Apex, tas pats API iškvietimas veikia ir ten; žr. Zapier Open Badges automatizavimas.

Ką kuriate

Srautą sudaro keturios dalys:

1. Ženklelis, sukurtas vizualiniame dizaineryje. Nukopijuokite jo id (id, kurį grąžina GET /badges).
2. API raktas, sukurtas jūsų skydelio puslapyje API Keys. Raktas rodomas tik vieną kartą, todėl iškart jį išsaugokite.
3. Named Credential Salesforce sistemoje, kuriame laikomas raktas, kad jis niekada nepatektų į kodą.
4. Apex trigeris ir Queueable klasė, kurie išduoda apdovanojimą ir įrašo apdovanojimo nuorodą atgal į įrašą.

1 žingsnis: išsaugokite raktą Named Credential

Užkoduoti API raktą tiesiai Apex kode yra klaida, kurios reikia vengti. Setup skiltyje sukurkite External Credential su pasirinktine antraštė, o tada Named Credential, nukreiptą į API serverį:

• URL: https://api.badges.ninja
• Custom header name: X-Api-Key
• Custom header value: jūsų raktas formatu bws_YOUR_KEY_HERE
• Named Credential name: BadgesNinja

Suteikite jūsų automatizavimą vykdančiam permission set prieigą prie External Credential principalo. Turint Named Credential, atskiro Remote Site Setting nereikia; Salesforce autorizuoja iškvietimą per credential. Jei jūsų organizacija vis dar naudoja senuosius Named Credentials ar paprastą endpoint, pridėkite https://api.badges.ninja kaip Remote Site Setting ir siųskite antraštę iš kodo.

2 žingsnis: pridėkite laukus prie įrašo

Objekte, kuris reprezentuoja pasiekimą (naudosime individualų objektą Training_Enrollment__c), pridėkite:

• Badge_Id__c (Text): išduotinas ženklelis. Saugant jį pagal kursą, vienas trigeris gali aptarnauti daug ženklelių.
• Badge_Award_Id__c (Text, unikalus): API grąžintas apdovanojimo id.
• Badge_Url__c (URL): viešas patikrinimo puslapis.
• Badge_Error__c (Long Text): paskutinė klaida, kad administratoriai matytų gedimus neatidarę derinimo žurnalų.

Laukas Badge_Award_Id__c atlieka dvi funkcijas. Tai jūsų apsauga nuo dublikatų: trigeris išduoda tik tada, kai jis tuščias.

3 žingsnis: Apex iškvietimas

Trigeris negali tiesiogiai atlikti iškvietimo, nes iškvietimai neleidžiami toje pačioje transakcijoje su nepatvirtintu DML. Perduokite darbą Queueable klasei, kuri įgyvendina Database.AllowsCallouts.

POST /awards API sutartis trumpa. Užklausos kūne yra badgeId, įdėtas recipient objektas su name ir email, bei privalomas issuedOn. Sėkmingas iškvietimas grąžina HTTP 200 su { "awardId": "..." }. Gavėjo vardas turi būti bent penkių simbolių, todėl Contact, pavadintas „Al Li“, būtų atmestas; patikrinkite prieš iškviesdami.

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

Verta atkreipti dėmesį į dvi detales. Pirma, issuedOn yra epochos milisekundės, būtent tai ir grąžina Datetime.getTime(). Antra, atsakyme nėra patikrinimo URL, todėl kodas jį sudaro iš apdovanojimo id: https://badges.ninja/awards/<awardId>.

4 žingsnis: trigeris

Trigeris turi būti plonas. Jis tik nusprendžia, kurie įrašai tinka, ir įdeda į eilę po vieną užduotį kiekvienam įrašui.

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

Patikra wasCompleted svarbi. Be jos bet koks vėlesnis baigto įrašo redagavimas vėl paleistų logiką. Kartu su tuščio apdovanojimo id apsauga užduotyje, įrašas gali sukurti tik vieną įgaliojimą.

Vienas apribojimas, kurį reikia atsiminti: Salesforce leidžia iš vienos transakcijos į eilę įdėti nedaug Queueable užduočių (50 sinchroniniame kontekste). Jei užbaigimus kraunate masiškai, pavyzdžiui, importuojate 2 000 eilučių, aukščiau pateiktas trigeris pasieks šią ribą. Masiniams įkėlimams arba įkelkite sąrašą per skydelio CSV masinius apdovanojimus, arba pereikite prie Batchable klasės su Database.AllowsCallouts, kuri kiekvienoje apimtyje apdoroja kelis įrašus.

Klaidų valdymas ir pakartojimai

API grąžina standartinius būsenos kodus, ir kiekvienas reikalauja skirtingo jūsų kodo atsako:

Kadangi užduotis įrašo klaidą į įrašą ir palieka Badge_Award_Id__c tuščią, pakartoti paprasta: pakanka pažymėti žymimąjį langelį arba iš naujo išsaugoti įrašą. Nedidelė suplanuota Apex klasė, ieškanti užbaigtų registracijų be apdovanojimo id ir su laikina klaida, o tada jas vėl įdedanti į eilę, suteikia automatinę pakartojimų eilę be jokios papildomos infrastruktūros. Apribokite bandymų skaičių skaitiklio lauku, kad visam laikui sugadintas įrašas nesisuktų be galo.

Prieš jungdami prie produkcinės aplinkos, patikrinkite savo planą. Free plane įtraukta 1 200 įgaliojimų per metus; Starter kainuoja $9 per mėnesį, o Pro — $29 per mėnesį. Trigeris, kuris suveikia kiekvienam Lead, mažą planą išnaudotų labai greitai, todėl kriterijus susiekite su tikrais pasiekimais.

Kaip įgaliojimą padaryti matomą Salesforce

Kai Badge_Url__c užpildytas, jį galite naudoti bet kur:

• El. laiškų įspėjimai ir šablonai: įtraukite lauką į laišką „Sveikiname, štai jūsų įgaliojimas“.
• Ataskaitos: ataskaita pagal Badge_Award_Id__c != null parodo išdavimų skaičių pagal kursą, regioną ar paskyros savininką.
• Experience Cloud: parodykite nuorodą partnerio sertifikavimo puslapyje, kad pirkėjai patys galėtų patikrinti.
• Puslapių išdėstymai: pridėkite URL lauką, kad palaikymo darbuotojai į klausimą „ar ji gavo savo ženklelį?“ atsakytų vienu žvilgsniu.

Patikrinimo puslapis yra viešas ir nereikalauja registracijos, ir tai yra visa esmė. Gavėjas, įdarbinimo vadovas ar kliento pirkimų komanda gali atidaryti nuorodą ir patvirtinti, kas išdavė įgaliojimą, ką jis liudija ir kada. Mašininiam patikrinimui bet kurio apdovanojimo Open Badge v2.0 JSON-LD pasiekiamas adresu https://api.badges.ninja/certify-badge/award/<awardId>.

Gavėjai taip pat gauna įprastus priedus: unikalią patikrinimo nuorodą, QR kodą, A4 PDF sertifikatą ir parinktį Add to LinkedIn gavėjo portale, į kurį jungiamasi magine nuoroda, o ne slaptažodžiu.

Kodėl tai pranašesnis už AppExchange ženklelių įskiepį

AppExchange ženklelių įskiepiai dažniausiai kainuoja pagal Salesforce vartotojų vietas arba valdomo paketo licencijas. Ši kaina auga kartu su jūsų Salesforce komandos dydžiu, o ne su išduodamų įgaliojimų skaičiumi, todėl dešimties žmonių mokymų komanda ir dešimties tūkstančių besimokančiųjų programa už tą patį rezultatą moka labai skirtingai.

API integracija šį modelį apverčia. Mokate pagal įgaliojimų kiekį fiksuotu planu, trigerio kodą galite skaityti ir keisti, o rezultatas yra standartinis Open Badge v2.0, todėl gavėjai nėra pririšti prie uždaro žiūryklės. Taip pat išlaikote dizaino laisvę: vizualiniame dizaineryje yra 80+ šablonų, formų, piktogramų ir individualių įkėlimų, o ne fiksuotas paketo maketas.

Sąžiningas kompromisas: įskiepis diegiamas keliais paspaudimais ir nereikalauja Apex. Jei jūsų komandoje niekas negali prižiūrėti kelių dešimčių kodo eilučių, įskiepis ar be kodo jungtis gali būti tinkamesnė. Jei lyginate platformas apskritai, o ne integracijas, Credly alternatyvos apžvalgoje kainos ir funkcijų skirtumai pateikiami greta.

Testavimas prieš paleidžiant

Pirmiausia visą srautą išbandykite smėlio dėžėje.

1. Sukurkite bandomąjį ženklelį ir bandomąjį gavėją su jūsų valdomu el. pašto adresu.
2. Apex testuose įgyvendinkite HttpCalloutMock, grąžinantį būseną 200 ir {"awardId":"test-award-id"}; Salesforce neleidžia tikrų iškvietimų testų kontekste, o šios aprėpties reikia diegimui.
3. Smėlio dėžėje nustatykite vieną registraciją į Completed ir patikrinkite, ar Badge_Award_Id__c ir Badge_Url__c užsipildo per minutę.
4. Atidarykite URL privačiame naršyklės lange ir įsitikinkite, kad viešas patikrinimo puslapis rodomas neprisijungus.
5. Sukelkite klaidą (palikite tuščią ženklelio id arba naudokite trumpesnį nei penkių simbolių gavėjo vardą) ir įsitikinkite, kad klaida atsiduria Badge_Error__c.

Pakeiskite API raktą, jei jis kada nors pateko į derinimo žurnalą ar ekrano nuotrauką. Atšaukimas įsigalioja iš karto API Keys puslapyje, o atnaujinti reikia tik External Credential, ne jūsų kodą.

Apibendrinimas

Šablonas nedidelis: plonas trigeris nusprendžia kada, Queueable atlieka iškvietimą, Named Credential saugo raktą, o trys įrašo laukai išsaugo rezultatą. Jis tinka mokymų etapams, partnerių lygiams, renginių lankomumui ar bet kokiam būsenos pokyčiui, kurį galite išreikšti Salesforce.

Pradėkite nuo vieno objekto ir vieno ženklelio, stebėkite savaitę ir plėskite, kai pakartojimų elgsena atitiks jūsų duomenis.

Pasiruošę išduoti pirmąjį patikrinamą įgaliojimą? Pradėkite nemokamai badges.ninja — vizualinis dizaineris, viešas patikrinimo puslapis, PDF sertifikatas, Open Badge v2.0 išvestis. Kredito kortelės nereikia.