Salesforce Open Badges: pārbaudāmu akreditācijas datu izsniegšana no CRM trigeriem

Lielākā daļa mācību komandu jau Salesforce uzskaita, kas ko ir pabeidzis. Kursa reģistrācija pāriet statusā „Completed”, partnera konts sasniedz sertifikācijas līmeni, klients pabeidz ievadapmācību. Ieraksts mainās, un pēc nedēļas kāds eksportē sarakstu un sertifikātus izsūta pa e-pastu ar roku.

Šī rokasgrāmata parāda, kā aizpildīt šo plaisu: kad ieraksts sasniedz jums svarīgo statusu, Salesforce izsauc https://badges.ninja API, tiek izsniegts Open Badge v2.0 akreditācijas dokuments, un verifikācijas saite tiek saglabāta atpakaļ ierakstā. Pēc tam šo saiti varat ievietot e-pasta veidnē, atskaitē vai Experience Cloud lapā.

Jums būs nepieciešams Salesforce administrators (vai izstrādātāja smilškaste), jau izveidota nozīme vietnē https://badges.ninja un API atslēga. Ja API vēl neesat izsaucis, vispirms izlasiet API ātro sākumu; tas aizņem desmit minūtes.

Kad CRM trigeris ir īstais rīks

Pirms rakstāt Apex, pārbaudiet, vai tas jums vispār vajadzīgs. Ja akreditācijas datus izsniedzat partijās reizi semestrī vai reizi ceturksnī, informācijas paneļa CSV augšupielāde ir ātrāka un neprasa nekādu kodu. Salesforce ceļš atmaksājas, kad:

• izsniegšanai jānotiek brīdī, kad ieraksts mainās, bez cilvēka soļa.
• dati par to, „kas to ir nopelnījis”, jau atrodas Salesforce un jūs nevēlaties otru patiesības avotu.
• vēlaties saglabāt akreditācijas saiti Contact, Lead vai pielāgotā mācību ierakstā atskaitēm.

Ja jūsu darbplūsmas rīks ir Zapier, nevis Apex, tas pats API izsaukums darbojas arī tur; skatiet Open Badges automatizācija ar Zapier.

Ko jūs veidojat

Plūsmai ir četras daļas:

1. Nozīme, kas izveidota vizuālajā dizainerī. Nokopējiet tās id (lauks id, ko atgriež GET /badges).
2. API atslēga, kas izveidota jūsu informācijas paneļa lapā API Keys. Atslēga tiek parādīta tikai vienreiz, tāpēc saglabājiet to uzreiz.
3. Named Credential Salesforce, kas glabā atslēgu, lai tā nekad neparādītos kodā.
4. Apex trigeris un Queueable klase, kas izsniedz apbalvojumu un ieraksta apbalvojuma saiti atpakaļ ierakstā.

1. solis: saglabājiet atslēgu Named Credential

API atslēgas iekodēšana tieši Apex ir kļūda, no kuras jāizvairās. Setup izveidojiet External Credential ar pielāgotu galveni, pēc tam Named Credential, kas norāda uz API resursdatoru:

• URL: https://api.badges.ninja
• Pielāgotās galvenes nosaukums: X-Api-Key
• Pielāgotās galvenes vērtība: jūsu atslēga formā bws_YOUR_KEY_HERE
• Named Credential nosaukums: BadgesNinja

Piešķiriet atļauju kopai, kas palaiž jūsu automatizāciju, piekļuvi External Credential principālim. Ar Named Credential jums nav vajadzīgs atsevišķs Remote Site Setting; Salesforce autorizē izsaukumu, izmantojot akreditācijas datus. Ja jūsu organizācija joprojām izmanto vecāka tipa Named Credentials vai parastu galapunktu, pievienojiet https://api.badges.ninja kā Remote Site Setting un sūtiet galveni no koda.

2. solis: pievienojiet ierakstam laukus

Objektam, kas pārstāv sasniegumu (izmantosim pielāgotu objektu Training_Enrollment__c), pievienojiet:

• Badge_Id__c (Text): izsniedzamā nozīme. Saglabājot to katram kursam, viens trigeris apkalpo daudzas nozīmes.
• Badge_Award_Id__c (Text, unique): API atgrieztais apbalvojuma id.
• Badge_Url__c (URL): publiskā verifikācijas lapa.
• Badge_Error__c (Long Text): pēdējā kļūda, lai administratori redzētu kļūmes, neatverot atkļūdošanas žurnālus.

Lauks Badge_Award_Id__c pilda divējādu lomu. Tā ir jūsu aizsardzība pret dublikātiem: trigeris izsniedz tikai tad, ja tas ir tukšs.

3. solis: Apex izsaukums

Trigeris nevar veikt izsaukumu tieši, jo izsaukumi nav atļauti vienā darījumā ar neapstiprinātu DML. Nododiet darbu Queueable klasei, kas implementē Database.AllowsCallouts.

POST /awards API līgums ir īss. Pamatteksts satur badgeId, ligzdotu recipient objektu ar name un email, kā arī obligātu issuedOn. Veiksmīgs izsaukums atgriež HTTP 200 ar { "awardId": "..." }. Saņēmēja vārdam jābūt vismaz piecu rakstzīmju garam, tāpēc Contact ar vārdu „Al Li” tiktu noraidīts; validējiet pirms izsaukuma.

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

Divas ievērības cienīgas detaļas. Pirmkārt, issuedOn ir epohas milisekundes, tieši to, ko atgriež Datetime.getTime(). Otrkārt, atbilde neietver verifikācijas URL, tāpēc kods to izveido no apbalvojuma id: https://badges.ninja/awards/<awardId>.

4. solis: trigeris

Turiet trigeri tievu. Tas tikai izlemj, kuri ieraksti atbilst, un ieliek rindā vienu darbu katram ierakstam.

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

Pārbaude wasCompleted ir svarīga. Bez tās jebkura vēlāka pabeigta ieraksta rediģēšana atkārtoti aktivizētu loģiku. Kopā ar tukša apbalvojuma id aizsardzību darbā ieraksts var izveidot tikai vienu akreditācijas dokumentu.

Viens ierobežojums, kas jāievēro: Salesforce ļauj no viena darījuma ielikt rindā nelielu skaitu Queueable darbu (sinhronā kontekstā 50). Ja pabeigšanas ielādējat masveidā, piemēram, ar 2000 rindu datu importu, iepriekš minētais trigeris sasniegs šo griestus. Masveida ielādēm saraksta vietā augšupielādējiet to, izmantojot informācijas paneļa CSV masveida apbalvojumus, vai pārejiet uz Batchable klasi ar Database.AllowsCallouts, kas katrā apjomā apstrādā dažus ierakstus.

Kļūdu apstrāde un atkārtoti mēģinājumi

API atgriež standarta statusa kodus, un katrs prasa no jūsu koda atšķirīgu reakciju:

Tā kā darbs ieraksta kļūdu ierakstā un atstāj Badge_Award_Id__c tukšu, atkārtots mēģinājums ir tikpat vienkāršs kā izvēles rūtiņas pārslēgšana vai ieraksta atkārtota saglabāšana. Neliela ieplānota Apex klase, kas meklē pabeigtas reģistrācijas bez apbalvojuma id un ar pārejošu kļūdu, pēc tam tās ieliek rindā no jauna, nodrošina automātisku atkārtojumu rindu bez papildu infrastruktūras. Ierobežojiet mēģinājumu skaitu ar skaitītāja lauku, lai pastāvīgi slikts ieraksts neciklotu bezgalīgi.

Pārbaudiet savu plānu, pirms pieslēdzat to produkcijai. Free plāns sedz 1200 akreditācijas datu gadā; Starter maksā 9 $ mēnesī, bet Pro — 29 $ mēnesī. Trigeris, kas aktivizējas katram Lead, ātri iztērētu nelielu plānu, tāpēc ierobežojiet kritērijus ar īstiem sasniegumiem.

Akreditācijas datu padarīšana redzamus Salesforce

Kad Badge_Url__c ir aizpildīts, to var izmantot jebkur:

• E-pasta brīdinājumi un veidnes: ievietojiet lauku e-pastā „Apsveicam, šeit ir jūsu akreditācijas dokuments”.
• Atskaites: atskaite pēc Badge_Award_Id__c != null dod izsniegšanas skaitu pēc kursa, reģiona vai konta īpašnieka.
• Experience Cloud: parādiet saiti partnera sertifikācijas lapā, lai pircēji paši varētu to pārbaudīt.
• Lapu izkārtojumi: pievienojiet URL lauku, lai atbalsta darbinieki uz jautājumu „vai viņa ir saņēmusi savu nozīmi?” varētu atbildēt ar vienu skatienu.

Verifikācijas lapa ir publiska un neprasa reģistrāciju, tā ir visa būtība. Saņēmējs, darba devējs vai klienta iepirkumu komanda var atvērt saiti un apstiprināt, kas akreditācijas dokumentu izsniedzis, ko tas apliecina un kad. Mašīnlasāmām pārbaudēm jebkura apbalvojuma Open Badge v2.0 JSON-LD ir pieejams adresē https://api.badges.ninja/certify-badge/award/<awardId>.

Saņēmēji iegūst arī ierastos papildus: unikālu verifikācijas URL, QR kodu, A4 PDF sertifikātu un Add to LinkedIn iespēju saņēmēju portālā, kurā pieteikšanās notiek ar burvju saiti, nevis paroli.

Kāpēc tas ir labāks par AppExchange nozīmju spraudni

AppExchange nozīmju spraudņu cenas parasti noteiktas par Salesforce lietotāju vai par pārvaldītās pakotnes licenci. Šīs izmaksas aug līdz ar jūsu Salesforce komandas lielumu, nevis izsniegto akreditācijas datu skaitu, tāpēc desmit cilvēku mācību komanda un desmit tūkstošu izglītojamo programma par vienādu rezultātu maksā ļoti atšķirīgi.

API integrācija šo modeli apgriež otrādi. Jūs maksājat pēc akreditācijas datu apjoma par fiksētu plānu, trigera kods ir jūsu — lasāms un maināms, un izvade ir standarta Open Badge v2.0, tāpēc saņēmēji nav piesaistīti patentētam skatītājam. Saglabājat arī dizaina brīvību: vizuālais dizainers piedāvā 80+ veidņu, formu, ikonu un pielāgotu augšupielāžu, nevis fiksētu izkārtojumu pakotnē.

Godīgs kompromiss: spraudni var uzstādīt ar vienu klikšķi, un tam nevajag Apex. Ja nevienam jūsu komandā nav iespējams uzturēt dažas desmitus koda rindu, spraudnis vai bezkoda savienotājs var būt labāka izvēle. Ja salīdzināt platformas kopumā, nevis integrācijas, Credly alternatīva apskata cenu un funkciju atšķirības blakus.

Testēšana pirms ieviešanas

Vispirms palaidiet visu plūsmu smilškastē.

1. Izveidojiet testa nozīmi un testa saņēmēju ar e-pasta adresi, kuru kontrolējat.
2. Apex testos implementējiet HttpCalloutMock, kas atgriež statusu 200 un {"awardId":"test-award-id"}; Salesforce testa kontekstā neatļauj īstus izsaukumus, un šis pārklājums jums nepieciešams izvietošanai.
3. Smilškastē iestatiet vienu reģistrāciju uz Completed un pārbaudiet, ka Badge_Award_Id__c un Badge_Url__c aizpildās minūtes laikā.
4. Atveriet URL privātā pārlūka logā, lai pārliecinātos, ka publiskā verifikācijas lapa tiek attēlota bez pieteikšanās.
5. Izraisiet kļūmi (iztukšojiet nozīmes id vai izmantojiet saņēmēja vārdu, kas īsāks par piecām rakstzīmēm) un pārliecinieties, ka kļūda nonāk Badge_Error__c.

Nomainiet API atslēgu, ja tā kādreiz nonāk atkļūdošanas žurnālā vai ekrānuzņēmumā. Atsaukšana ir tūlītēja lapā API Keys, un jums jāatjaunina tikai External Credential, nevis kods.

Noslēgumā

Šablons ir mazs: tievs trigeris izlemj, kad, Queueable veic izsaukumu, Named Credential glabā atslēgu, bet trīs lauki ierakstā saglabā rezultātu. Tas der mācību pavērsiena punktiem, partneru līmeņiem, pasākumu apmeklējumam vai jebkurai stāvokļa izmaiņai, ko varat izteikt Salesforce.

Sāciet ar vienu objektu un vienu nozīmi, vērojiet to nedēļu un paplašiniet, kad atkārtoto mēģinājumu uzvedība atbilst jūsu datiem.

Gatavi izsniegt savu pirmo pārbaudāmo akreditācijas dokumentu? Sāciet bez maksas badges.ninja platformā — vizuālais dizainers, publiska verifikācijas lapa, PDF sertifikāts, Open Badge v2.0 izvade. Kredītkarte nav nepieciešama.