salesforce
+
+

Lab 1: Updating master data with Salesforce Bulk API

Overview

As you integrate Salesforce with other systems you will come across use cases such as:

  • Initial loads of data, for instance during migrations or to prepare the Salesforce objects for a new release

  • Regular updates of parametric or master data such as currency conversion tables or product attributes and prices.

  • Export, and deletion of a selection of data for the purpose of archiving

In this lab we will have a look at how Mulesoft leverages Salesforce’s Bulk API to handle changes with large amounts of data.

Our goal is to create or update ("upsert") the customers in Salesforce based on the contents of a CSV file.

Step 1: Download the CSV file

Download the CSV file with the customers here: Sample Accounts

Customers will map to Salesforce’s Account object.

Step 2: Add the External Id to Accounts

Salesforce APIs support the UPSERT operation, which basically creates a new record if the key is not present in the object, or updates the record if the key was found.

UPSERT requries an external Id, which we will create in these steps.

2.1 Navigate to Object Manager

  • Log into your Salesforce Org and click on Setup, and then Setup. Salesforce Setup Cog 2022 11 11 at 18.06.08

  • Click into the Object Manager Salesforce Setup Object Manager 2022 11 11 at 18.08.08

  • Find the object Account

  • Add a new Field of Text with length 12

  • Check the External ID checkbox Salesforce Setup Account External ID 2022 11 11 at 18.12.31

  • Click Next

  • Click Next

  • Save

2.2 Verify the layout

To verify that the field has been added, please open an Account fo your choice, and check that the field appears in the Details:

Salesfroce Account External ID in Detail 2022 11 11 at 18.16.50

Step 3: Create a new empty Mule Project

In this step we will create a new Mule application in Anypoint Studio from scratch. It implements the logic of a batch API.

Step 3.1: If this is your first Anypoint Studio project

Example 1. Anypoint Studio setup instructions for the first time.

  1. Start Anypoint Studio from the desktop icon.

    Anypoint Platform Home Page

  2. In the Workspace Launcher, use the default workspace directory location.

  3. In the pop-up window click on Continue to Studio

  4. You are now inside Anypoint Studio. First, let’s sync your Anypoint Platform account with Anypoint Studio. Go to Window → Preferences (for windows) or Anypoint Studio → Preference (for Mac) to open the Anypoint Studio Preferences.

  5. Then go to Anypoint Studio → Authentication. If you see your account name there, skip to step 7. If not, click the Add button.

    Create Button

  6. Login to your Anypoint Platform workshop account. Then click Apply and Close.

    API Editor

Step 3.2: Create a new project

  1. We are now going to start creating our new Mule project. Click on File → New → Mule Project

    file new

  2. Set the Project Name to salesforce-bulk-load

    Create New Project salesforce bulk load Screenshot 2021 12 13 at 10.05.17

  3. You can click Finish. This will create an empty project.

Step 4: Add the Saleforce Connector and the File Connector modules

  1. Navigate to the Mule Palette in the upper right Navigate to Modules Screenshot 2021 12 10 at 14.35.58

    Add the Salesforce Connector Module, by dragging it from the Modules Palette from the right onto the left:

    Add the Salesforce Module Screenshot 2021 12 10 at 14.36.23

    Once added you can explore the different invocations available in the Salesforce Connector for Bulk API V2. In this lab we will focus on the upsert of records using the Bulk API V2.

    After adding the Salesforce Module Screenshot 2021 12 10 at 14.36.39

  2. Because we will be upserting data contained in a file, we need to add the File module to read it. Repeat the previous steps to add the File Module. The Mule Palette then looks like this Mule Palette with Modules Screenshot 2021 12 13 at 10.29.32

Step 5: Configure the File Connector

  1. Add the File Module’s On New or Updated File to the project by drag-and-dropping it

  2. Configure its properties as follows:

    1. Connector Configuration:

      • On your laptop create an empty directory that serves as the home for the files being processed. For example, you could define it to be /tmp/bulk on a Mac. Under this directory create these subdirectories:

        • in

        • out

      • Set the path in the Connector Properties to /tmp/bulk File Reader Working Directory Screenshot 2021 12 10 at 14.43.15

    2. Directory: Is a directory that will be polled for new files. The files will be processed as soon as they are placed on that directory. Set this value to in

    3. Scheduling Strategy: To define the polling on the directory to once per second, set it to Fixed Frequency with these parameters:

      • Frequency 1000

      • Start delay: 0

      • Time unit: MILLISECONDS

    4. Move to directory: set it to out to specify the directory the file is moved to, after reading finishes. Set this value to out

      File Reader config Screenshot 2021 12 10 at 14.43.57

Step 6: Configure the Salesforce Connector

  1. Add the Salesforce Create job bulk api v2 to the project

  2. Let’s now configure the invocation:

    1. Connector configuration: add the authentication credentials to the Connector Configuration

      Salesforce Connector Configuration 2022 11 11 at 17.45.51

      Provide a Security Token if your Salesforce Org requires it.

  3. Once the connection has been configured and tested, you can now configure the Bulk API invocation. The parameters are:

    1. Object type: Account

    2. Operation: Upsert

    3. External id field name: External_Id__c

      Salesforce Upser Bulk API configuration Screenshot 2021 12 13 at 11.33.30

Step 7: Transform the records from the file to the Account sObject

Now the Message Flow in the project looks like this: Flow after adding the Create Job Bulk API V2 call Screenshot 2021 12 10 at 15.50.38

  1. From the Mule Palette (n the upper right corner) choose Favorites → Transform Message and place it between the two:

  2. Click on Define metadata. Click on add (green cross). Enter AccountsCSV and click on Create type.

  3. Set the Type to: CSV and open the accounts.csv file you downloaded in [Step 1. Download the CSV file].

  4. Check the Wrap element in a collection box and click OK

    anypoint csv metadata type

  5. Click on Select

  6. Add the following mapping to the Transform Message. Note that Create Job Bulk API V2 requires the input data to be a CSV. The DataWeave therefore generates application/csv

    %dw 2.0
output application/csv
---
payload map (val, index) -> {
	BillingStreet: val.street,
	BillingCity: val.city,
	BillingPostalCode: val.zip,
	BillingCountry: val.country,
	Phone: val.phone,
	External_ID__c: val.externalId,
	Name: val.firstName ++ " " ++ val.lastName
}

    The Transform Message then looks like this:

    Bulk API Transform Message 2022 11 11 at 17.55.31

Step 8: Try it out

  1. Run the Mulesoft App by clicking the green Play buttton Run the project Screenshot 2021 12 13 at 11.51.56

  2. Verify the job completed successfully in Salesforce, Setup → Environments → Jobs → Bulk Data Load Jobs

    Salesforce Bulk API Status Screenshot 2021 12 13 at 11.49.37

Congratulations! You have successfully designed, built and deployed your first API!

Summary

In this lab, you were able to successfuly upsert records in Salesforce by usisng the Bulk API V2.

You completed the following steps:

Take me to the TOP

Submit your feedback!
Share your thoughts to help us build the best workshop experience for you!
Take our latest survey!