Salesforce Open Badges: Myönnä varmennettavia todistuksia CRM-triggereistä

Useimmat koulutustiimit kirjaavat jo Salesforceen, kuka on suorittanut mitä. Kurssi-ilmoittautuminen siirtyy tilaan “Completed”, kumppanitili saavuttaa sertifiointitason, asiakas pääsee onboardingin loppuun. Tietue muuttuu, ja viikkoa myöhemmin joku vie listan ulos ja lähettää todistukset käsin sähköpostilla.

Tämä opas näyttää, miten tuo aukko suljetaan: kun tietue saavuttaa haluamasi tilan, Salesforce kutsuu https://badges.ninja-API:a, Open Badge v2.0 -todistus myönnetään ja varmennuslinkki tallennetaan takaisin tietueelle. Sen jälkeen voit lisätä linkin sähköpostipohjaan, raporttiin tai Experience Cloud -sivulle.

Tarvitset Salesforce-ylläpitäjän (tai developer sandboxin), jo suunnitellun badgen osoitteessa https://badges.ninja ja API-avaimen. Jos et ole koskaan kutsunut API:a, lue ensin API-pikaopas. Siihen menee kymmenen minuuttia.

Milloin CRM-triggeri on oikea työkalu

Ennen kuin kirjoitat Apexia, tarkista, tarvitsetko sitä. Jos myönnät todistukset erissä kerran lukukaudessa tai neljännesvuodessa, koontinäytön CSV-lataus on nopeampi eikä vaadi lainkaan koodia. Salesforce-reitti kannattaa, kun:

• Myöntämisen pitää tapahtua heti tietueen muuttuessa ilman ihmisen tekemää vaihetta.
• Tieto siitä, kuka on ansainnut todistuksen, on jo Salesforcessa, etkä halua toista totuuden lähdettä.
• Haluat tallentaa todistuslinkin Contactiin, Leadiin tai omaan koulutustietueeseen raportointia varten.

Jos työnkulkutyökalusi on Apexin sijaan Zapier, sama API-kutsu toimii myös siellä; katso Zapier Open Badges -automaatio.

Mitä olet rakentamassa

Kulussa on neljä osaa:

1. Badge, joka on suunniteltu visuaalisessa suunnittelutyökalussa. Kopioi sen id (GET /badges palauttaa id:n).
2. API-avain, joka luodaan koontinäytön API Keys -sivulla. Avain näytetään vain kerran, joten tallenna se heti.
3. Named Credential Salesforcessa, joka säilyttää avaimen, jotta se ei koskaan näy koodissa.
4. Apex-triggeri ja Queueable-luokka, jotka myöntävät palkinnon ja kirjoittavat palkintolinkin takaisin tietueelle.

Vaihe 1: Tallenna avain Named Credentialiin

API-avaimen kovakoodaaminen Apexiin on virhe, jota kannattaa välttää. Luo Setupissa External Credential, jossa on mukautettu header, ja sen jälkeen Named Credential, joka osoittaa API-palvelimeen:

• URL: https://api.badges.ninja
• Custom header name: X-Api-Key
• Custom header value: avaimesi muodossa bws_YOUR_KEY_HERE
• Named Credential name: BadgesNinja

Anna automaatiotasi ajavalle permission setille pääsy External Credentialin principaliin. Kun Named Credential on käytössä, erillistä Remote Site Settingiä ei tarvita; Salesforce valtuuttaa kutsun credentialin kautta. Jos organisaatiosi käyttää vielä vanhoja Named Credentialeja tai tavallista endpointia, lisää https://api.badges.ninja Remote Site Settingiksi ja lähetä header koodista.

Vaihe 2: Lisää kentät tietueelle

Lisää suoritusta kuvaavalle objektille (käytämme mukautettua objektia nimeltä Training_Enrollment__c):

• Badge_Id__c (Text): myönnettävä badge. Kun tallennat sen kurssikohtaisesti, yksi triggeri voi palvella monta badgea.
• Badge_Award_Id__c (Text, unique): API:n palauttama palkinnon id.
• Badge_Url__c (URL): julkinen varmennussivu.
• Badge_Error__c (Long Text): viimeisin virhe, jotta ylläpitäjät näkevät viat avaamatta debug-lokeja.

Kentällä Badge_Award_Id__c on kaksi tehtävää. Se on kaksoiskappaleiden estäjäsi: triggeri myöntää vain, kun kenttä on tyhjä.

Vaihe 3: Apex-kutsu

Triggeri ei voi tehdä kutsua suoraan, koska kutsut eivät ole sallittuja samassa transaktiossa committaamattoman DML:n kanssa. Anna työ Queueable-luokalle, joka toteuttaa Database.AllowsCallouts-rajapinnan.

POST /awards -rajapinnan sopimus on lyhyt. Body sisältää badgeId:n, sisäkkäisen recipient-objektin, jossa on name ja email, sekä pakollisen issuedOn:n. Onnistunut kutsu palauttaa HTTP 200:n ja { "awardId": "..." }. Vastaanottajan nimen on oltava vähintään viisi merkkiä, joten Contact nimeltä “Al Li” hylättäisiin; validoi ennen kutsua.

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

Kaksi yksityiskohtaa ansaitsee huomion. Ensinnäkin issuedOn on epoch-millisekunteja, täsmälleen sitä, mitä Datetime.getTime() palauttaa. Toiseksi vastaus ei sisällä varmennus-URL:ia, joten koodi rakentaa sen palkinnon id:stä: https://badges.ninja/awards/<awardId>.

Vaihe 4: Triggeri

Pidä triggeri ohuena. Se vain päättää, mitkä tietueet kelpaavat, ja lisää yhden työn jonoon tietuetta kohden.

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

wasCompleted-tarkistus on tärkeä. Ilman sitä mikä tahansa myöhempi muokkaus suoritettuun tietueeseen käynnistäisi logiikan uudelleen. Yhdessä työn sisällä olevan tyhjän palkinto-id:n tarkistuksen kanssa tietue voi tuottaa vain yhden todistuksen.

Yhtä rajaa on kunnioitettava: Salesforce sallii vain pienen määrän Queueable-töitä jonoon yhdestä transaktiosta (50 synkronisessa kontekstissa). Jos lataat suorituksia massana, esimerkiksi 2 000 rivin tuonnissa, yllä oleva triggeri osuu tähän kattoon. Massalatauksissa joko lataa lista koontinäytön CSV-massamyöntönä tai vaihda Batchable-luokkaan, jossa on Database.AllowsCallouts ja joka käsittelee muutaman tietueen scopea kohden.

Virheenkäsittely ja uudelleenyritykset

API palauttaa standardit tilakoodit, ja jokainen vaatii koodiltasi oman vastauksensa:

Koska työ kirjoittaa virheen tietueelle ja jättää Badge_Award_Id__c:n tyhjäksi, uudelleenyritys on yhtä helppo kuin valintaruudun kääntäminen tai tietueen tallentaminen uudelleen. Pieni ajastettu Apex-luokka, joka etsii suoritetut ilmoittautumiset, joilla ei ole palkinto-id:tä ja joilla on ohimenevä virhe, ja lisää ne uudelleen jonoon, antaa sinulle automaattisen uudelleenyritysjonon ilman lisäinfrastruktuuria. Rajoita yritysten määrä laskurikentällä, jotta pysyvästi virheellinen tietue ei kierrä silmukassa ikuisesti.

Tarkista suunnitelmasi ennen kuin kytket tämän tuotantoon. Free-suunnitelma kattaa 1 200 todistusta vuodessa; Starter maksaa $9 kuukaudessa ja Pro $29 kuukaudessa. Jokaisessa Leadissa laukeava triggeri kuluttaisi pienen suunnitelman nopeasti, joten rajaa ehdot todellisiin saavutuksiin.

Todistuksen tekeminen näkyväksi Salesforcessa

Kun Badge_Url__c on täytetty, voit käyttää sitä missä tahansa:

• Sähköpostihälytykset ja -pohjat: yhdistä kenttä “Onnittelut, tässä on todistuksesi” -sähköpostiin.
• Raportit: raportti ehdolla Badge_Award_Id__c != null kertoo myöntöjen määrän kurssin, alueen tai tilin omistajan mukaan.
• Experience Cloud: näytä linkki kumppanin sertifiointisivulla, jotta ostajat voivat varmentaa sen itse.
• Page layoutit: lisää URL-kenttä, jotta tukihenkilöstö voi vastata kysymykseen “saiko hän badgensa?” yhdellä silmäyksellä.

Varmennussivu on julkinen eikä vaadi rekisteröitymistä, ja juuri se on koko pointti. Vastaanottaja, rekrytoija tai asiakkaan hankintatiimi voi avata linkin ja vahvistaa, kuka todistuksen myönsi, mitä se sertifioi ja milloin. Koneluettavia tarkistuksia varten minkä tahansa palkinnon Open Badge v2.0 JSON-LD on saatavilla osoitteessa https://api.badges.ninja/certify-badge/award/<awardId>.

Vastaanottajat saavat myös tavanomaiset lisät: yksilöllisen varmennus-URL:in, QR-koodin, A4-kokoisen PDF-todistuksen ja Add to LinkedIn -vaihtoehdon vastaanottajaportaalista, johon kirjaudutaan magic linkillä salasanan sijaan.

Miksi tämä päihittää AppExchangen badge-lisäosan

AppExchangen badge-lisäosat hinnoitellaan yleensä Salesforce-käyttäjäpaikan tai managed package -lisenssin mukaan. Tuo kustannus skaalautuu Salesforce-tiimisi koon mukaan, ei myöntämiesi todistusten määrän mukaan, joten kymmenen hengen koulutustiimi ja kymmenentuhatta oppijaa käsittävä ohjelma maksavat samasta lopputuloksesta aivan eri summat.

API-integraatio kääntää mallin toisin päin. Maksat todistusmäärän mukaan kiinteällä suunnitelmalla, triggerikoodi on sinun luettavissasi ja muokattavissasi, ja tuloste on standardi Open Badge v2.0, joten vastaanottajat eivät ole sidottuja suljettuun katseluohjelmaan. Säilytät myös suunnitteluvapautesi: visuaalinen suunnittelutyökalu tarjoaa yli 80 mallia, muotoa, kuvaketta ja omia latauksia kiinteän pakettiin sidotun ulkoasun sijaan.

Rehellinen kompromissi: lisäosa asennetaan yhdellä klikkauksella eikä vaadi Apexia. Jos tiimissäsi kukaan ei voi ylläpitää muutamaa kymmentä koodiriviä, lisäosa tai no-code-liitin voi sopia paremmin. Jos vertailet alustoja yleisesti integraatioiden sijaan, Credly-vaihtoehto-vertailu käy läpi hinnat ja ominaisuuserot rinnakkain.

Testaus ennen tuotantoon siirtymistä

Aja koko kulku ensin sandboxissa.

1. Luo testibadge ja testivastaanottaja sähköpostiosoitteella, jota hallitset.
2. Toteuta Apex-testeissä HttpCalloutMock, joka palauttaa tilan 200 ja {"awardId":"test-award-id"}; Salesforce ei salli oikeita kutsuja testikontekstissa, ja tarvitset tämän kattavuuden julkaisuun.
3. Aseta sandboxissa yksi ilmoittautuminen tilaan Completed ja tarkista, että Badge_Award_Id__c ja Badge_Url__c täyttyvät minuutissa.
4. Avaa URL yksityisessä selainikkunassa varmistaaksesi, että julkinen varmennussivu latautuu ilman kirjautumista.
5. Aiheuta virhe (tyhjennä badge-id tai käytä alle viiden merkin vastaanottajan nimeä) ja varmista, että virhe päätyy kenttään Badge_Error__c.

Vaihda API-avain, jos se koskaan vuotaa debug-lokiin tai kuvakaappaukseen. Mitätöinti on välitön API Keys -sivulta, ja sinun tarvitsee päivittää vain External Credential, ei koodiasi.

Yhteenveto

Malli on pieni: ohut triggeri päättää milloin, Queueable tekee kutsun, Named Credential säilyttää avaimen ja kolme kenttää tietueella tallentaa lopputuloksen. Se toimii koulutuksen virstanpylväille, kumppanitasoille, tapahtumaosallistumiselle tai mille tahansa tilanmuutokselle, jonka voit ilmaista Salesforcessa.

Aloita yhdellä objektilla ja yhdellä badgella, seuraa sitä viikko ja laajenna, kun uudelleenyritysten toiminta sopii datallesi.

Valmiina myöntämään ensimmäisen varmennettavan todistuksesi? Aloita ilmaiseksi badges.ninjassa — visuaalinen suunnittelutyökalu, julkinen varmennussivu, PDF-todistus, Open Badge v2.0 -tuloste. Luottokorttia ei tarvita.