Salesforce Open Badges: Έκδοση επαληθεύσιμων διαπιστευτηρίων από triggers του CRM

Οι περισσότερες ομάδες εκπαίδευσης καταγράφουν ήδη μέσα στο Salesforce ποιος ολοκλήρωσε τι. Μια εγγραφή σε μάθημα περνά στο «Completed», ένας λογαριασμός συνεργάτη φτάνει σε επίπεδο πιστοποίησης, ένας πελάτης ολοκληρώνει το onboarding. Η εγγραφή αλλάζει και, μία εβδομάδα αργότερα, κάποιος εξάγει μια λίστα και στέλνει τα πιστοποιητικά με email με το χέρι.

Αυτός ο οδηγός δείχνει πώς να κλείσετε αυτό το κενό: όταν μια εγγραφή φτάσει στην κατάσταση που σας ενδιαφέρει, το Salesforce καλεί το API του https://badges.ninja, εκδίδεται ένα διαπιστευτήριο Open Badge v2.0 και ο σύνδεσμος επαλήθευσης αποθηκεύεται πίσω στην εγγραφή. Στη συνέχεια μπορείτε να βάλετε αυτόν τον σύνδεσμο σε ένα πρότυπο email, σε μια αναφορά ή σε μια σελίδα του Experience Cloud.

Θα χρειαστείτε έναν διαχειριστή Salesforce (ή ένα developer sandbox), ένα ψηφιακό σήμα που έχει ήδη σχεδιαστεί στο https://badges.ninja και ένα API key. Αν δεν έχετε καλέσει ποτέ το API, διαβάστε πρώτα το API quickstart· χρειάζονται δέκα λεπτά.

Πότε το trigger του CRM είναι το σωστό εργαλείο

Πριν γράψετε Apex, ελέγξτε αν το χρειάζεστε. Αν εκδίδετε διαπιστευτήρια σε παρτίδες μία φορά το εξάμηνο ή το τρίμηνο, το ανέβασμα CSV από το dashboard είναι ταχύτερο και δεν απαιτεί καθόλου κώδικα. Η διαδρομή μέσω Salesforce αξίζει όταν:

• Η έκδοση πρέπει να γίνεται τη στιγμή που αλλάζει μια εγγραφή, χωρίς ανθρώπινο βήμα.
• Τα δεδομένα για το «ποιος το κέρδισε» υπάρχουν ήδη στο Salesforce και δεν θέλετε δεύτερη πηγή αλήθειας.
• Θέλετε ο σύνδεσμος του διαπιστευτηρίου να αποθηκεύεται στο Contact, στο Lead ή στη δική σας εγγραφή εκπαίδευσης για αναφορές.

Αν το εργαλείο ροής εργασίας σας είναι το Zapier και όχι το Apex, η ίδια κλήση API λειτουργεί και εκεί· δείτε το Zapier Open Badges automation.

Τι θα φτιάξετε

Η ροή έχει τέσσερα κομμάτια:

1. Ένα ψηφιακό σήμα σχεδιασμένο στον οπτικό σχεδιαστή. Αντιγράψτε το id του (το id που επιστρέφει το GET /badges).
2. Ένα API key που δημιουργείται στη σελίδα API Keys του dashboard σας. Το κλειδί εμφανίζεται μία φορά, γι’ αυτό αποθηκεύστε το αμέσως.
3. Ένα Named Credential στο Salesforce που κρατά το κλειδί, ώστε να μην εμφανίζεται ποτέ στον κώδικα.
4. Ένα Apex trigger και μια κλάση Queueable που εκδίδουν την απονομή και γράφουν τον σύνδεσμό της πίσω στην εγγραφή.

Βήμα 1: Αποθηκεύστε το κλειδί σε ένα Named Credential

Η σκληρή κωδικοποίηση ενός API key στο Apex είναι το λάθος που πρέπει να αποφύγετε. Στο Setup, δημιουργήστε ένα External Credential με custom header και έπειτα ένα Named Credential που δείχνει στον host του API:

• URL: https://api.badges.ninja
• Όνομα custom header: X-Api-Key
• Τιμή custom header: το κλειδί σας, στη μορφή bws_YOUR_KEY_HERE
• Όνομα Named Credential: BadgesNinja

Δώστε στο permission set που εκτελεί την αυτοματοποίησή σας πρόσβαση στο principal του External Credential. Με ένα Named Credential στη θέση του δεν χρειάζεστε ξεχωριστό Remote Site Setting· το Salesforce εξουσιοδοτεί το callout μέσω του credential. Αν ο οργανισμός σας εξακολουθεί να χρησιμοποιεί legacy Named Credentials ή απλό endpoint, προσθέστε το https://api.badges.ninja ως Remote Site Setting και στείλτε το header από τον κώδικα.

Βήμα 2: Προσθέστε πεδία στην εγγραφή

Στο αντικείμενο που αντιπροσωπεύει το επίτευγμα (θα χρησιμοποιήσουμε ένα custom αντικείμενο με όνομα Training_Enrollment__c), προσθέστε:

• Badge_Id__c (Text): το ψηφιακό σήμα που θα εκδοθεί. Αν το αποθηκεύετε ανά μάθημα, ένα trigger εξυπηρετεί πολλά σήματα.
• Badge_Award_Id__c (Text, unique): το id απονομής που επιστρέφει το API.
• Badge_Url__c (URL): η δημόσια σελίδα επαλήθευσης.
• Badge_Error__c (Long Text): το τελευταίο σφάλμα, ώστε οι διαχειριστές να βλέπουν τις αποτυχίες χωρίς να ανοίγουν debug logs.

Το πεδίο Badge_Award_Id__c κάνει διπλή δουλειά. Είναι η προστασία σας από διπλότυπα: το trigger εκδίδει μόνο όταν είναι κενό.

Βήμα 3: Το Apex callout

Ένα trigger δεν μπορεί να κάνει callout απευθείας, επειδή τα callouts δεν επιτρέπονται στην ίδια συναλλαγή με DML που δεν έχει γίνει commit. Αναθέστε τη δουλειά σε ένα Queueable που υλοποιεί το Database.AllowsCallouts.

Το συμβόλαιο API για το POST /awards είναι σύντομο. Το σώμα περιέχει το badgeId, ένα εμφωλευμένο αντικείμενο recipient με name και email, και το υποχρεωτικό issuedOn. Μια επιτυχημένη κλήση επιστρέφει HTTP 200 με { "awardId": "..." }. Το όνομα του παραλήπτη πρέπει να έχει τουλάχιστον πέντε χαρακτήρες, οπότε ένα Contact με όνομα «Al Li» θα απορριφθεί· κάντε επικύρωση πριν την κλήση.

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

Δύο λεπτομέρειες αξίζουν προσοχή. Πρώτον, το issuedOn είναι epoch σε χιλιοστά του δευτερολέπτου, ακριβώς αυτό που επιστρέφει το Datetime.getTime(). Δεύτερον, η απάντηση δεν περιλαμβάνει το URL επαλήθευσης, γι’ αυτό ο κώδικας το χτίζει από το id απονομής: https://badges.ninja/awards/<awardId>.

Βήμα 4: Το trigger

Κρατήστε το trigger λιτό. Αποφασίζει μόνο ποιες εγγραφές πληρούν τα κριτήρια και βάζει στην ουρά μία εργασία ανά εγγραφή.

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 έχει σημασία. Χωρίς αυτόν, κάθε μεταγενέστερη επεξεργασία μιας ολοκληρωμένης εγγραφής θα ενεργοποιούσε ξανά τη λογική. Σε συνδυασμό με τον έλεγχο κενού award id μέσα στην εργασία, μια εγγραφή μπορεί να παράγει μόνο ένα διαπιστευτήριο.

Ένα όριο που πρέπει να σεβαστείτε: το Salesforce επιτρέπει μικρό αριθμό Queueable εργασιών να μπουν στην ουρά από μία συναλλαγή (50 σε σύγχρονο περιβάλλον). Αν φορτώνετε ολοκληρώσεις μαζικά, π.χ. εισαγωγή δεδομένων 2.000 γραμμών, το παραπάνω trigger θα χτυπήσει αυτό το όριο. Για μαζικές φορτώσεις, είτε ανεβάστε τη λίστα μέσω των μαζικών απονομών CSV του dashboard, είτε περάστε σε κλάση Batchable με Database.AllowsCallouts που επεξεργάζεται λίγες εγγραφές ανά scope.

Διαχείριση σφαλμάτων και επαναπροσπάθειες

Το API επιστρέφει τυπικούς κωδικούς κατάστασης και ο καθένας απαιτεί διαφορετική αντίδραση από τον κώδικά σας:

Επειδή η εργασία γράφει το σφάλμα στην εγγραφή και αφήνει κενό το Badge_Award_Id__c, η επαναπροσπάθεια είναι τόσο απλή όσο το γύρισμα ενός checkbox ή η επανα-αποθήκευση της εγγραφής. Μια μικρή προγραμματισμένη κλάση Apex που αναζητά ολοκληρωμένες εγγραφές χωρίς award id και με παροδικό σφάλμα και τις βάζει ξανά στην ουρά σάς δίνει αυτόματη ουρά επαναπροσπαθειών χωρίς επιπλέον υποδομή. Περιορίστε τις προσπάθειες με ένα πεδίο μετρητή, ώστε μια μόνιμα προβληματική εγγραφή να μην κάνει βρόχο επ’ άπειρον.

Ελέγξτε το πλάνο σας πριν το συνδέσετε στην παραγωγή. Το Free πλάνο καλύπτει 1.200 διαπιστευτήρια τον χρόνο· το Starter κοστίζει $9 τον μήνα και το Pro $29 τον μήνα. Ένα trigger που ενεργοποιείται σε κάθε Lead θα εξαντλούσε γρήγορα ένα μικρό πλάνο, γι’ αυτό περιορίστε τα κριτήρια σε πραγματικά επιτεύγματα.

Κάντε το διαπιστευτήριο ορατό στο Salesforce

Μόλις συμπληρωθεί το Badge_Url__c, μπορείτε να το χρησιμοποιήσετε οπουδήποτε:

• Email alerts και πρότυπα: συγχωνεύστε το πεδίο σε ένα email «Συγχαρητήρια, ιδού το διαπιστευτήριό σας».
• Αναφορές: μια αναφορά στο Badge_Award_Id__c != null σάς δίνει μετρήσεις εκδόσεων ανά μάθημα, περιοχή ή ιδιοκτήτη λογαριασμού.
• Experience Cloud: εμφανίστε τον σύνδεσμο στη σελίδα πιστοποίησης ενός συνεργάτη, ώστε οι αγοραστές να τον επαληθεύουν μόνοι τους.
• Page layouts: προσθέστε το πεδίο URL ώστε το προσωπικό υποστήριξης να απαντά στο «πήρε το ψηφιακό σήμα της;» με μια ματιά.

Η σελίδα επαλήθευσης είναι δημόσια και δεν απαιτεί εγγραφή, κι αυτό είναι το νόημα. Ένας παραλήπτης, ένας υπεύθυνος πρόσληψης ή το τμήμα προμηθειών ενός πελάτη μπορεί να ανοίξει τον σύνδεσμο και να επιβεβαιώσει ποιος εξέδωσε το διαπιστευτήριο, τι πιστοποιεί και πότε. Για ελέγχους από μηχανές, το JSON-LD Open Badge v2.0 κάθε απονομής είναι διαθέσιμο στο https://api.badges.ninja/certify-badge/award/<awardId>.

Οι παραλήπτες παίρνουν επίσης τα συνηθισμένα πρόσθετα: ένα μοναδικό URL επαλήθευσης, έναν κωδικό QR, ένα πιστοποιητικό PDF σε A4 και επιλογή Add to LinkedIn από την πύλη παραλήπτη, η οποία συνδέει με magic link αντί για κωδικό πρόσβασης.

Γιατί υπερτερεί ενός plugin ψηφιακών σημάτων του AppExchange

Τα plugins ψηφιακών σημάτων στο AppExchange τείνουν να τιμολογούνται ανά θέση Salesforce ή ανά άδεια managed package. Αυτό το κόστος αυξάνεται με το μέγεθος της ομάδας σας στο Salesforce και όχι με τον αριθμό των διαπιστευτηρίων που εκδίδετε, οπότε μια ομάδα εκπαίδευσης δέκα ατόμων και ένα πρόγραμμα δέκα χιλιάδων εκπαιδευομένων πληρώνουν πολύ διαφορετικά για το ίδιο αποτέλεσμα.

Μια ενσωμάτωση API αναστρέφει αυτό το μοντέλο. Πληρώνετε ανά όγκο διαπιστευτηρίων με ένα σταθερό πλάνο, ο κώδικας του trigger είναι δικός σας να τον διαβάζετε και να τον αλλάζετε, και το αποτέλεσμα είναι τυπικό Open Badge v2.0, οπότε οι παραλήπτες δεν είναι δεσμευμένοι σε ιδιόκτητο πρόγραμμα προβολής. Διατηρείτε επίσης την ελευθερία σχεδιασμού: ο οπτικός σχεδιαστής προσφέρει 80+ πρότυπα, σχήματα, εικονίδια και custom uploads, αντί για σταθερή διάταξη μέσα σε ένα package.

Το ειλικρινές αντιστάθμισμα: ένα plugin εγκαθίσταται με ένα κλικ και δεν χρειάζεται Apex. Αν κανείς στην ομάδα σας δεν μπορεί να συντηρήσει μερικές δεκάδες γραμμές κώδικα, ένα plugin ή ένας no-code connector μπορεί να ταιριάζει καλύτερα. Αν συγκρίνετε πλατφόρμες γενικά και όχι ενσωματώσεις, η ανάλυση Credly alternative καλύπτει τιμές και διαφορές χαρακτηριστικών δίπλα δίπλα.

Δοκιμή πριν βγείτε στην παραγωγή

Τρέξτε πρώτα όλη τη ροή σε ένα sandbox.

1. Δημιουργήστε ένα δοκιμαστικό ψηφιακό σήμα και έναν δοκιμαστικό παραλήπτη με διεύθυνση email που ελέγχετε.
2. Στα Apex tests, υλοποιήστε ένα HttpCalloutMock που επιστρέφει status 200 και {"awardId":"test-award-id"}· το Salesforce δεν επιτρέπει πραγματικά callouts σε περιβάλλον test και χρειάζεστε αυτή την κάλυψη για να κάνετε deploy.
3. Στο sandbox, ορίστε μία εγγραφή σε Completed και ελέγξτε ότι τα Badge_Award_Id__c και Badge_Url__c συμπληρώνονται μέσα σε ένα λεπτό.
4. Ανοίξτε το URL σε ιδιωτικό παράθυρο προγράμματος περιήγησης για να επιβεβαιώσετε ότι η δημόσια σελίδα επαλήθευσης εμφανίζεται χωρίς σύνδεση.
5. Προκαλέστε αποτυχία (αφήστε κενό το id του σήματος ή χρησιμοποιήστε όνομα παραλήπτη κάτω των πέντε χαρακτήρων) και επιβεβαιώστε ότι το σφάλμα καταλήγει στο Badge_Error__c.

Αλλάξτε το API key αν ποτέ διαρρεύσει σε debug log ή σε στιγμιότυπο οθόνης. Η ανάκληση είναι άμεση από τη σελίδα API Keys και χρειάζεται να ενημερώσετε μόνο το External Credential, όχι τον κώδικά σας.

Συνοψίζοντας

Το μοτίβο είναι μικρό: ένα λιτό trigger αποφασίζει πότε, ένα Queueable κάνει το callout, ένα Named Credential κρατά το κλειδί και τρία πεδία στην εγγραφή αποθηκεύουν το αποτέλεσμα. Λειτουργεί για ορόσημα εκπαίδευσης, επίπεδα συνεργατών, συμμετοχή σε εκδηλώσεις ή οποιαδήποτε αλλαγή κατάστασης μπορείτε να εκφράσετε στο Salesforce.

Ξεκινήστε με ένα αντικείμενο και ένα ψηφιακό σήμα, παρακολουθήστε το για μια εβδομάδα και επεκταθείτε όταν η συμπεριφορά των επαναπροσπαθειών ταιριάζει στα δεδομένα σας.

Έτοιμοι να εκδώσετε το πρώτο σας επαληθεύσιμο διαπιστευτήριο; Ξεκινήστε δωρεάν στο badges.ninja — οπτικός σχεδιαστής, δημόσια σελίδα επαλήθευσης, πιστοποιητικό PDF, έξοδος Open Badge v2.0. Χωρίς πιστωτική κάρτα.