Using a Salesforce APEX Trigger to upsert a Lead

🔗 Before you start

This article is written for advanced users of Salesforce that understand Apex code and are comfortable with Apex triggers. If you are new to Salesforce there are a few Trailhead modules we recommend reading to get you started.

• Apex Basics & Database - Trailhead Module
• Apex Triggers - Trailhead Module

To get started you will need:

• The SaaSquatch for Salesforce managed package installed in your organization. If not follow the install guide
• A Salesforce user with permission to use the Developer Console.

🔗 Create a new Trigger

To start open the Developer Console from inside of Salesforce.

We are going to create a new Apex Trigger. Create one by going to File -> New -> Apex Trigger

We will be triggering on Lead objects after insert. You can name the trigger something that won't conflict with other trigger names in your environment.

trigger TutorialForSaaSquatch on Lead (after insert, after update) {
    for (Lead lead : Trigger.new) {
        // Iterate over each sObject
    }
}

For this example we are triggering on Lead, but organizations may also want to trigger on Contact updates as well. That would require different code in the Apex trigger, but most of this tutorial would still apply.

🔗 Build records to insert

We're going to be building up ReferralSaaSquatchUpsertUserByIdReq objects to send to the SaaSquatch API. Since triggers operate on batches, we're going to create a List of objects to build up.

trigger TutorialForSaaSquatch on Lead (after insert, after update) {
    List<SaaSquatch.ReferralSaaSquatchUpsertUserByIdReq> users = new List<SaaSquatch.ReferralSaaSquatchUpsertUserByIdReq>();
    for (Lead lead : Trigger.new) {
        // Iterate over each sObject
    }
}

For each Lead that has been inserted or updated in this trigger we are going to copy that data to SaaSquatch. In this example we're going to use Email as the unique ID in SaaSquatch. We're also to use the immediatelyUpsertObjects flag to make sure that the SaaSquatch User, Referral and RewardBalance custom objects get updated immediately.

trigger TutorialForSaaSquatch on Lead (after insert, after update) {
    List<SaaSquatch.ReferralSaaSquatchUpsertUserByIdReq> users = new List<SaaSquatch.ReferralSaaSquatchUpsertUserByIdReq>();
    for (Lead lead : Trigger.new) {
        // Iterate over each sObject
        SaaSquatch.ReferralSaaSquatchUpsertUserByIdReq user = new SaaSquatch.ReferralSaaSquatchUpsertUserByIdReq();

        // Uses `Email` as the ID
        user.userId=lead.Email;
        user.accountId=lead.Email;

        // Syncs `FirstName` and `Email`
        user.firstName=lead.FirstName;
        user.email=lead.Email;

        // Tracks who referred this person
        user.referredByCodes=lead.CodeUsed__c;

        // Tells the integration to immediately update corresponding objects in Salesforce
        user.immediatelyUpsertObjects=true;
        users.add(user);
    }
}

We're using Immediate Object Upsertion in this example so that the SaaSquatch Custom Objects are updated in Salesforce as quickly as possible. Alternatively the Salesforce background sync will periodically update records if this is turned off.

🔗 Call the Invocable Method

Now that we have a list of users to send to SaaSquatch, we need to call the SaaSquatch invocable method to send the data to SaaSquatch.

We're sending the users list to the ReferralSaaSquatchUpsertUserById invocable method.

SaaSquatch.ReferralSaaSquatchUpsertUserById.upsertUsers(users);

For this example we're using ReferralSaaSquatchUpsertUserById but there are other InvocableMethods in the SaaSquatch package that may suite your use case, such as logging events and upserting based a linked standard object.

The final code should end up looking like this:

trigger TutorialForSaaSquatch on Lead (after insert, after update) {
    List<SaaSquatch.ReferralSaaSquatchUpsertUserByIdReq> users = new List<SaaSquatch.ReferralSaaSquatchUpsertUserByIdReq>();
    for (Lead lead : Trigger.new) {
        // Iterate over each sObject
        SaaSquatch.ReferralSaaSquatchUpsertUserByIdReq user = new SaaSquatch.ReferralSaaSquatchUpsertUserByIdReq();

        // Uses `Email` as the ID
        user.userId=lead.Email;
        user.accountId=lead.Email;

        // Syncs `FirstName` and `Email`
        user.firstName=lead.FirstName;
        user.email=lead.Email;

        // Tracks who referred this person
        user.referredByCodes=lead.CodeUsed__c;

        // Tells the integration to immediately update corresponding objects in Salesforce
        user.immediatelyUpsertObjects=true;
        users.add(user);
    }
    // Queues a callout to the SaaSquatch API
    SaaSquatch.ReferralSaaSquatchUpsertUserById.upsertUsers(users);
}

🔗 Test the lead trigger

To test that this trigger is working:

• Save your trigger
• Make sure there are no alerts in the Problems tab of the Developer Console
• Create a new Lead in Salesforce
• Open the SaaSquatch Admin Portal to confirm that a User has been created in SaaSquatch.

🔗 Conclusion

In this tutorial we walked through creating a new trigger on Lead to send data to SaaSquatch whenever data is changed in Salesforce. Since the SaaSquatch API uses batches behind the scenes this create a low-overhead and near-realtime way of synchronizing data between Salesforce and SaaSquatch in order to trigger your referral and loyalty programs.