Salesforce Open Badges: CRM Tetikleyicileriyle Doğrulanabilir Kimlik Bilgileri Verin

Çoğu eğitim ekibi, kimin neyi tamamladığını zaten Salesforce içinde kaydediyor. Bir kurs kaydı “Completed” durumuna geçer, bir iş ortağı hesabı sertifikasyon seviyesine ulaşır, bir müşteri onboarding’i bitirir. Kayıt değişir, ardından bir hafta sonra biri bir liste dışa aktarıp sertifikaları elle e-postayla gönderir.

Bu rehber, bu boşluğu nasıl kapatacağınızı gösteriyor: bir kayıt önem verdiğiniz duruma ulaştığında Salesforce https://badges.ninja API’sini çağırır, bir Open Badge v2.0 kimlik bilgisi düzenlenir ve doğrulama bağlantısı kayda geri yazılır. Ardından bu bağlantıyı bir e-posta şablonuna, bir rapora veya bir Experience Cloud sayfasına ekleyebilirsiniz.

Bir Salesforce yöneticisine (veya bir geliştirici sandbox’ına), https://badges.ninja üzerinde önceden tasarlanmış bir rozete ve bir API anahtarına ihtiyacınız olacak. API’yi daha önce hiç çağırmadıysanız önce API hızlı başlangıç kılavuzunu okuyun; on dakika sürer.

CRM tetikleyicisinin doğru araç olduğu durumlar

Apex yazmadan önce buna gerçekten ihtiyacınız olup olmadığını kontrol edin. Kimlik bilgilerini dönemde bir veya üç ayda bir toplu olarak düzenliyorsanız, kontrol panelindeki CSV yüklemesi daha hızlıdır ve hiç kod gerektirmez. Salesforce yolu şu durumlarda değerini kanıtlar:

• Düzenleme, kayıt değiştiği anda, hiçbir insan adımı olmadan gerçekleşmeliyse.
• “Kim hak etti” verisi zaten Salesforce’ta duruyorsa ve ikinci bir doğruluk kaynağı istemiyorsanız.
• Raporlama için kimlik bilgisi bağlantısını Contact, Lead veya özel eğitim kaydında saklamak istiyorsanız.

İş akışı aracınız Apex yerine Zapier ise aynı API çağrısı orada da çalışır; bkz. Zapier ile Open Badges otomasyonu.

Ne inşa ediyorsunuz

Akış dört parçadan oluşur:

1. Görsel tasarımcıda tasarlanmış bir rozet. Kimliğini kopyalayın (GET /badges çağrısının döndürdüğü id).
2. Kontrol panelinizin API Keys sayfasında oluşturulmuş bir API anahtarı. Anahtar yalnızca bir kez gösterilir, bu yüzden hemen saklayın.
3. Anahtarı tutan, böylece kodda hiç görünmeyen, Salesforce’ta bir Named Credential.
4. Ödülü düzenleyen ve ödül bağlantısını kayda geri yazan bir Apex tetikleyicisi ile bir Queueable sınıfı.

Adım 1: Anahtarı bir Named Credential’da saklayın

Bir API anahtarını Apex’e sabit olarak yazmak, kaçınmanız gereken hatadır. Setup’ta özel başlıklı bir External Credential, ardından API ana bilgisayarını gösteren bir Named Credential oluşturun:

• URL: https://api.badges.ninja
• Özel başlık adı: X-Api-Key
• Özel başlık değeri: bws_YOUR_KEY_HERE biçiminde anahtarınız
• Named Credential adı: BadgesNinja

Otomasyonunuzu çalıştıran izin kümesine External Credential’ın principal’ine erişim verin. Named Credential varken ayrı bir Remote Site Setting’e ihtiyacınız yoktur; Salesforce çağrıyı kimlik bilgisi üzerinden yetkilendirir. Kuruluşunuz hâlâ eski Named Credential’ları veya düz bir endpoint kullanıyorsa https://api.badges.ninja adresini Remote Site Setting olarak ekleyin ve başlığı koddan gönderin.

Adım 2: Kayda alanlar ekleyin

Başarıyı temsil eden nesneye (Training_Enrollment__c adlı özel bir nesne kullanacağız) şunları ekleyin:

• Badge_Id__c (Text): düzenlenecek rozet. Bunu kurs başına saklamak, tek bir tetikleyicinin birçok rozete hizmet etmesini sağlar.
• Badge_Award_Id__c (Text, benzersiz): API’nin döndürdüğü ödül kimliği.
• Badge_Url__c (URL): herkese açık doğrulama sayfası.
• Badge_Error__c (Long Text): son hata; böylece yöneticiler hata ayıklama günlüklerini açmadan başarısızlıkları görebilir.

Badge_Award_Id__c alanı çifte görev yapar. Yinelenenlere karşı korumanızdır: tetikleyici yalnızca bu alan boşsa düzenleme yapar.

Adım 3: Apex çağrısı

Bir tetikleyici doğrudan callout yapamaz, çünkü callout’lara, henüz commit edilmemiş DML ile aynı işlemde izin verilmez. İşi Database.AllowsCallouts uygulayan bir Queueable’a devredin.

POST /awards için API sözleşmesi kısadır. Gövde badgeId, name ve email içeren iç içe bir recipient nesnesi ve zorunlu bir issuedOn taşır. Başarılı bir çağrı, { "awardId": "..." } ile HTTP 200 döndürür. Alıcı adı en az beş karakter olmalıdır, dolayısıyla “Al Li” adlı bir Contact reddedilir; çağırmadan önce doğrulayın.

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

Dikkat edilmesi gereken iki ayrıntı var. Birincisi, issuedOn epoch milisaniyesidir; tam olarak Datetime.getTime() değerinin döndürdüğü şeydir. İkincisi, yanıt doğrulama URL’sini içermez, bu yüzden kod onu ödül kimliğinden oluşturur: https://badges.ninja/awards/<awardId>.

Adım 4: Tetikleyici

Tetikleyiciyi ince tutun. Yalnızca hangi kayıtların uygun olduğuna karar verir ve kayıt başına bir iş kuyruğa alır.

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 kontrolü önemlidir. O olmadan, tamamlanmış bir kayıtta sonradan yapılan her düzenleme mantığı yeniden tetiklerdi. İşin içindeki boş ödül kimliği korumasıyla birleştiğinde, bir kayıt yalnızca tek bir kimlik bilgisi üretebilir.

Saygı göstermeniz gereken bir sınır var: Salesforce, tek bir işlemden kuyruğa alınabilecek Queueable iş sayısını sınırlı tutar (eşzamanlı bağlamda 50). Tamamlanmaları toplu yüklüyorsanız, örneğin 2.000 satırlık bir veri aktarımında, yukarıdaki tetikleyici bu tavana takılır. Toplu yüklemeler için ya listeyi bunun yerine kontrol panelindeki CSV toplu ödülleri ile yükleyin ya da kapsam başına birkaç kaydı işleyen, Database.AllowsCallouts içeren bir Batchable sınıfına geçin.

Hata yönetimi ve yeniden denemeler

API standart durum kodları döndürür ve her biri kodunuzdan farklı bir yanıt gerektirir:

İş hatayı kayda yazdığı ve Badge_Award_Id__c alanını boş bıraktığı için yeniden deneme, bir onay kutusunu çevirmek veya kaydı yeniden kaydetmek kadar basittir. Ödül kimliği olmayan ve geçici hata almış tamamlanmış kayıtları arayıp yeniden kuyruğa alan küçük bir zamanlanmış Apex sınıfı, ek altyapı olmadan size otomatik bir yeniden deneme kuyruğu verir. Kalıcı olarak hatalı bir kaydın sonsuza kadar dönmemesi için denemeleri bir sayaç alanıyla sınırlayın.

Bunu üretime bağlamadan önce planınızı kontrol edin. Free plan yılda 1.200 kimlik bilgisini kapsar; Starter ayda $9, Pro ise ayda $29’dır. Her Lead’de tetiklenen bir tetikleyici küçük bir planı hızla tüketir, bu yüzden ölçütleri gerçek başarılarla sınırlayın.

Kimlik bilgisini Salesforce’ta görünür kılmak

Badge_Url__c dolduktan sonra onu her yerde kullanabilirsiniz:

• E-posta uyarıları ve şablonları: alanı “Tebrikler, kimlik bilginiz burada” e-postasına birleştirin.
• Raporlar: Badge_Award_Id__c != null üzerine kurulu bir rapor, kurs, bölge veya hesap sahibine göre düzenleme sayılarını verir.
• Experience Cloud: bağlantıyı bir iş ortağının sertifikasyon sayfasında gösterin; böylece alıcılar kendileri doğrulayabilir.
• Sayfa düzenleri: URL alanını ekleyin; destek ekibi “Rozetini aldı mı?” sorusunu tek bakışta yanıtlayabilsin.

Doğrulama sayfası herkese açıktır ve kayıt gerektirmez; asıl amaç da budur. Bir alıcı, bir işe alım yöneticisi veya bir müşterinin satın alma ekibi bağlantıyı açıp kimlik bilgisini kimin düzenlediğini, neyi onayladığını ve ne zaman verildiğini doğrulayabilir. Makine tarafından okunabilir kontroller için herhangi bir ödülün Open Badge v2.0 JSON-LD çıktısı https://api.badges.ninja/certify-badge/award/<awardId> adresinde bulunur.

Alıcılar ayrıca olağan ekstraları da alır: benzersiz bir doğrulama URL’si, bir QR kodu, A4 boyutunda PDF sertifika ve parola yerine magic link ile giriş yapılan alıcı portalında LinkedIn’e Ekle seçeneği.

Bunun bir AppExchange rozet eklentisinden daha iyi olmasının nedeni

AppExchange’teki rozet eklentileri genellikle Salesforce kullanıcı başına veya yönetilen paket lisansı başına fiyatlandırılır. Bu maliyet, düzenlediğiniz kimlik bilgisi sayısıyla değil Salesforce ekibinizin büyüklüğüyle ölçeklenir; dolayısıyla on kişilik bir eğitim ekibi ile on bin öğrencili bir program aynı çıktı için çok farklı ödeme yapar.

API entegrasyonu bu modeli tersine çevirir. Sabit bir planda kimlik bilgisi hacmine göre ödersiniz, tetikleyici kodu sizindir; okuyabilir ve değiştirebilirsiniz, çıktı da standart Open Badge v2.0’dır, yani alıcılar tescilli bir görüntüleyiciye bağımlı kalmaz. Tasarım özgürlüğünüzü de korursunuz: görsel tasarımcı, bir paket içindeki sabit bir düzen yerine 80+ şablon, şekil, simge ve özel yükleme sunar.

Dürüst takas şu: bir eklenti tek tıkla kurulur ve Apex gerektirmez. Ekibinizde birkaç düzine satır kodu bakımda tutabilecek kimse yoksa bir eklenti veya kodsuz bir bağlayıcı daha uygun olabilir. Entegrasyonları değil de platformları genel olarak karşılaştırıyorsanız, Credly alternatifi incelemesi fiyat ve özellik farklarını yan yana ele alır.

Canlıya geçmeden önce test etme

Tüm akışı önce bir sandbox’ta çalıştırın.

1. Bir test rozeti ve kontrolünüzdeki bir e-posta adresine sahip bir test alıcısı oluşturun.
2. Apex testlerinde 200 durumu ve {"awardId":"test-award-id"} döndüren bir HttpCalloutMock uygulayın; Salesforce test bağlamında gerçek callout’lara izin vermez ve dağıtım için bu kapsama ihtiyacınız vardır.
3. Sandbox’ta bir kaydı Completed yapın ve Badge_Award_Id__c ile Badge_Url__c alanlarının bir dakika içinde dolduğunu kontrol edin.
4. Herkese açık doğrulama sayfasının oturum açmadan göründüğünü doğrulamak için URL’yi özel bir tarayıcı penceresinde açın.
5. Bir hata oluşturun (rozet kimliğini boşaltın veya beş karakterden kısa bir alıcı adı kullanın) ve hatanın Badge_Error__c alanına düştüğünü doğrulayın.

API anahtarı bir hata ayıklama günlüğüne veya ekran görüntüsüne sızarsa anahtarı yenileyin. İptal, API Keys sayfasından anında gerçekleşir ve yalnızca External Credential’ı güncellemeniz gerekir, kodunuzu değil.

Toparlarken

Desen küçüktür: ince bir tetikleyici ne zaman olacağına karar verir, bir Queueable çağrıyı yapar, bir Named Credential anahtarı tutar ve kayıttaki üç alan sonucu saklar. Eğitim aşamaları, iş ortağı seviyeleri, etkinlik katılımı veya Salesforce’ta ifade edebileceğiniz her durum değişikliği için çalışır.

Tek bir nesne ve tek bir rozetle başlayın, bir hafta izleyin ve yeniden deneme davranışı verilerinize uyduğunda genişletin.

İlk doğrulanabilir kimlik bilginizi düzenlemeye hazır mısınız? badges.ninja’da ücretsiz başlayın — görsel tasarımcı, herkese açık doğrulama sayfası, PDF sertifika, Open Badge v2.0 çıktısı. Kredi kartı gerekmez.