Feed

Salesforce Sales Cloud is a Customer Relationship Management (CRM) platform designed to manage leads, opportunities, and customer relationships to drive sales growth. Salesforce Service Cloud focuses on customer support, case management, and self-service solutions to improve customer satisfaction.

The Salesforce feed integration allows mParticle to receive data from Sales and Service Cloud. The integration uses data forwarded from Salesforce to mParticle via Salesforce Apex and Handler, which is captured through the mParticle Events API. Once events flow into mParticle, you can use them to build audiences, power downstream tools, and enrich your customer data.

Setup overview

1. Create a feed input in mParticle: This generates a server-to-server key and secret, which will be used to authenticate API calls from Salesforce.
2. Configure Salesforce authentication with named credentials: You’ll set up an external credential and named credential in Salesforce, which securely store your mParticle API credentials and endpoint information. This avoids hard-coding secret keys.
3. Create an apex trigger and handler in Salesforce: The trigger listens for changes in your Salesforce data (for example, a record being created or updated) and passes the information to a handler class. The handler determines event types to send to mParticle.
4. Implement a callout class: The callout class formats the Salesforce data into the JSON payload expected by the mParticle Events API, uses the named credential for authentication, and makes the outbound HTTP request.
5. Test and verify in mParticle: By inserting or updating Salesforce records, you can confirm that events are being sent correctly and are visible in mParticle’s Live Stream.

Prerequisites

• Salesforce admin privileges to create external credentials, principals, permission sets, and named credentials.
• Salesforce developer access to create a custom object, apex trigger, and apex classes.
• mParticle account access with permission to create a feed input.

To set up a new connection, please complete the following steps in sequence.

Part 1: Create a feed input in mParticle

1. Log in to your mParticle account, and go to Data Platform > Setup > Inputs using the left-hand navigation.
2. Go to the Feeds tab.
3. Click the Add Feed Input button and select Salesforce Sales and Service Cloud. Alternatively, if you already have a feed, scroll down the page and click the + next to Salesforce Sales and Service Cloud to add a new configuration.
4. Name your configuration, leave Feed Status as Active.

5. Choose an Input Protection level:

   • Create and Update Profiles: allows all profile modifications and additions.
   • Only Update Profiles: allows profile modifications only to preexisting profiles in the identity scope, but prevents any new profile additions.
   • Read Only: prevents any profile modifications or new profile additions.
6. Click Save and copy the generated Server-to-Server Key and Server-to-Server Secret. You will use this in the next subsection to configure authentication (Basic Auth) in Salesforce.

Part 2: Configure Salesforce authentication (named credentials)

Salesforce recommends using both Named Credentials and External Credentials. This keeps secrets out of code and lets you authorize who can make callouts.

2.1 Create an external credential (basic authentication)

1. Log in to your Salesforce account.
2. In the Setup page, navigate to Security > Named Credentials > External Credentials, and then click New.
3. Enter a Label and Name.
4. Set the Authentication Protocol to Basic Authentication and click Save.

5. In the Principals section of your External Credential, click New to create a Named Principal and populate:

   • Username: add your mParticle Server-to-Server Key captured previously
   • Password: add your mParticle Server-to-Server Secret captured previously
6. Click Save.

2.2 Grant access with a permission set (principal access)

1. In Setup, open Permission Sets and click New.
2. Give it a name such as mParticle Callouts and click Save.
3. In the permission set, open External Credential Principal Access, click Edit, and move your principal to Enabled External Credential Principals.
4. Click Manage Assignments > Add Assignments, and assign the permission set to the users or integration user that will run the callouts.
5. Select Basic Authentication in the Authentication Protocol dropdown.

2.3 Create a Named Credential that points to mParticle

1. In Setup > Named Credentials, click New.
2. Enter a Label and Name (for example, mP_API).
3. Under URL, enter the mParticle Event API URL for your location (for example, https://s2s.mparticle.com/v2/events). See Data Hosting Locations to find the correct URL for your account’s hosting location.
4. Select the External Credential you created above.
5. Check Enabled for Callouts, then click Save.

In Apex, you will call this endpoint using the callout:<NamedCredentialName> syntax.

Part 3: Create the apex trigger and handler

You need to do this with each of your objects. To illustrate the integration, this guide uses a custom object called TestTicket__c with fields including Status__c (picklist: Open, In Progress, Closed) and Email__c. Two example events are sent:

• Ticket Created when a record is inserted and has an email.
• Ticket Closed when Status__c changes to Closed and the record has an email.

3.1 What is an Apex Trigger and Handler?

Below is a brief explanation of a few key Salesforce terms to help you better understand and set up the following sections.

Apex Trigger

An Apex Trigger is a small piece of code in Salesforce that runs automatically when certain database events occur, such as when a record is created, updated, or deleted. Triggers enable you to automate actions that happen “behind the scenes,” without requiring a user to click a button or run a process manually.

Handler Class

A Handler is a separate Apex class where you put the actual business logic that the trigger calls. Instead of writing all the logic directly in the trigger, you forward the work to the handler. This makes the code easier to read, maintain, and extend in the future.

Why they matter here

In this integration, the trigger detects changes in Salesforce (for example, when a new record is created or an existing record’s status changes). The trigger then calls the handler, which builds the event payload and sends it out to the mParticle Events API.

In summary:

• Trigger: watches for changes in your Salesforce data.
• Handler: decides what to do with those changes (in this case, send events to mParticle).

3.2 Create the Apex Trigger

1. In Salesforce, go to Setup.
2. In the Quick Find box, type Apex Triggers and click Apex Triggers.
3. Click New.
4. From the Object dropdown, select your object (for example, TestTicket__c).
5. Enter a Name (for example, TicketTrigger).
6. Paste in the trigger code provided below.
7. Click Save.

Trigger code sample

trigger TicketTrigger on TestTicket__c (after insert, after update) {
    if (Trigger.isAfter) {
        if (Trigger.isInsert) {
            TicketTriggerHandler.handleAfterInsert(Trigger.new);
        } else if (Trigger.isUpdate) {
            TicketTriggerHandler.handleAfterUpdate(Trigger.oldMap, Trigger.newMap);
        }
    }
}

3.3 Create the Apex Handler Class

1. In Salesforce, go to Setup.
2. In the Quick Find box, type Apex Classes and click Apex Classes.
3. Click New.
4. Enter a Class Name (for example, TicketTriggerHandler).
5. Paste in the handler class code provided below.
6. Click Save.

Once saved, Salesforce immediately compiles the trigger and handler. Any time a record event (insert or update) matches your trigger conditions, Salesforce will run the logic in the handler and send the event to mParticle.

Handler code sample

public class TicketTriggerHandler {
    public static void handleAfterInsert(List<TestTicket__c> newTickets) {
        for (TestTicket__c t : newTickets) {
            if (String.isNotBlank(t.Email__c)) {
                MParticleIntegration.sendTicketCreatedEvent(t.Email__c, t.Id, t.Name);
            }
        }
    }

    public static void handleAfterUpdate(Map<Id, TestTicket__c> oldMap, Map<Id, TestTicket__c> newMap) {
        for (Id id : newMap.keySet()) {
            TestTicket__c oldT = oldMap.get(id), newT = newMap.get(id);
            Boolean wasNotClosed = oldT.Status__c != 'Closed';
            Boolean isNowClosed  = newT.Status__c == 'Closed';
            if (wasNotClosed && isNowClosed && String.isNotBlank(newT.Email__c)) {
                MParticleIntegration.sendTicketClosedEvent(newT.Email__c, newT.Id, newT.Name);
            }
        }
    }
}

Part 4: Implement the mParticle callout class

In Salesforce, a callout is any outbound HTTP request that Salesforce makes to an external system. A callout class is simply an apex class designed to handle these outbound requests. It usually sets up the endpoint, authentication, headers, and body of the request, then sends it and processes the response.

In this integration, the callout class is responsible for sending the event data from Salesforce to mParticle:

• It formats your Salesforce data into the JSON shape expected by the mParticle Events API.
• It uses your Named Credential to securely add authentication details and point to the correct regional endpoint.
• It sends the request and logs whether it succeeded or failed.

By separating this logic into a dedicated callout class, you keep your trigger and handler simple (they just detect changes and hand off the work). The callout class handles all the details of making the actual API request.

4.1 Create the callout class

1. In Salesforce, go to Setup.
2. In the Quick Find box, type Apex Classes and click Apex Classes.
3. Click New.
4. Enter a Class Name (for example, MParticleIntegration).
5. Paste in the full callout class code sample below.
6. Click Save.

After saving, Salesforce will compile the class. Since the methods are marked with @future(callout=true), they can be invoked by your handler asynchronously and will be allowed to make HTTP callouts to the mParticle Events API. The actual endpoint and authentication are managed by the Named Credential you configured earlier.

Callout class code sample

public class MParticleIntegration {
    @future(callout=true)
    public static void sendTicketCreatedEvent(String email, Id recordId, String ticketName) {
        String orgBase = System.URL.getOrgDomainUrl().toExternalForm();
        String recordUrl = orgBase + '/' + recordId;

        Map<String, Object> event = new Map<String, Object>{
            'event_type' => 'custom_event',
            'data' => new Map<String, Object>{
                'event_name' => 'Ticket Created',
                'custom_event_type' => 'other',
                'custom_attributes' => new Map<String, Object>{ 'Ticket Name' => ticketName }
            }
        };

        Map<String, Object> payload = new Map<String, Object>{
            'events' => new List<Object>{ event },
            'user_identities' => new Map<String, Object>{ 'email' => email },
            'user_attributes' => new Map<String, Object>{ 'Last Open Ticket' => recordUrl },
            'environment' => 'development'
        };

        sendMParticleEvent(payload, 'Ticket Created');
    }

    @future(callout=true)
    public static void sendTicketClosedEvent(String email, Id recordId, String ticketName) {
        Map<String, Object> event = new Map<String, Object>{
            'event_type' => 'custom_event',
            'data' => new Map<String, Object>{
                'event_name' => 'Ticket Closed',
                'custom_event_type' => 'other',
                'custom_attributes' => new Map<String, Object>{ 'Ticket Name' => ticketName }
            }
        };

        Map<String, Object> payload = new Map<String, Object>{
            'events' => new List<Object>{ event },
            'user_identities' => new Map<String, Object>{ 'email' => email },
            'environment' => 'development'
        };

        sendMParticleEvent(payload, 'Ticket Closed');
    }

    private static void sendMParticleEvent(Map<String, Object> payload, String label) {
        HttpRequest req = new HttpRequest();
        // Named Credential created in Part 2.3
        req.setEndpoint('callout:mP_API/events');
        req.setMethod('POST');
        req.setHeader('Content-Type', 'application/json');
        req.setBody(JSON.serialize(payload));

        Http http = new Http();
        HttpResponse res = http.send(req);

        if (res.getStatusCode() >= 200 && res.getStatusCode() < 300) {
            System.debug(label + ' sent to mParticle. ' + res.getStatus());
        } else {
            System.debug('mParticle error: ' + res.getStatus() + ' - ' + res.getBody());
        }
    }
}

Part 5: Test the integration

Before going live, test the integration to confirm that Salesforce triggers and callouts are functioning correctly and that events arrive in mParticle as expected. You can use the Salesforce Developer Console to insert and update sample records, review logs, and then verify the resulting events in mParticle’s Live Stream.

5.1 Open the Developer Console

1. In Salesforce, click your avatar in the top right corner.
2. Select Developer Console.

5.2 Insert a test record

1. In the Developer Console, go to Debug > Open Execute Anonymous Window.
2. Paste the following code and click Execute:

TestTicket__c t = new TestTicket__c(
    Email__c='test@example.com',
    Details__c='Something went wrong'
);
insert t;

3. This insert fires the trigger and queues the Ticket Created callout.

5.3 Check the callout job

1. In the Developer Console, open the Logs tab.
2. Look for a log entry from the MParticleIntegration class.
3. Open the log and confirm that the HTTP request was sent and returned a 200/202 response.

5.4 Verify the event in mParticle Live Stream

1. Log in to your mParticle account.
2. Open Live Stream.
3. Set Environment to Development (the example payloads use environment: "development").
4. Filter by Source to your Salesforce Sales and Service Cloud feed if needed.
5. Search for the email address test@example.com.
6. Confirm that you see a Ticket Created event.

5.5 Update the record to trigger “Ticket Closed”

1. In the Developer Console, open the Execute Anonymous window again.
2. Paste the following code and click Execute:

TestTicket__c t = [
    SELECT Id FROM TestTicket__c 
    WHERE Email__c='test@example.com' 
    ORDER BY CreatedDate DESC LIMIT 1
];
t.Status__c = 'Closed';
update t;

3. This update fires the trigger and queues the Ticket Closed callout.
4. Repeat steps 5.3 and 5.4 to confirm that the Apex job has completed and that a Ticket Closed event appears in mParticle Live Stream.

5.6 Capture debug logs (optional)

If you want detailed System.debug output:

1. In the Developer Console, go to Debug > Change Log Levels.
2. Set Apex Code to DEBUG.
3. Re-run the insert/update steps, then open the resulting logs to inspect debug output from your trigger, handler, and callout class.

Part 6: Expected results

• Logs show successful execution of the MParticleIntegration methods.
• In Live Stream, you see the corresponding Ticket Created and Ticket Closed events for the email identity you used.