Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.

Creating a Salesforce Upsert Operation

This page described how to create a Salesforce Upsert operation using the Jitterbit Connect Salesforce Upsert Wizard.

The Salesforce Upsert activity allows you to update existing or insert new records in a connected Salesforce instance using Jitterbit. An "upsert" is essentially either an update or an insert operation, or both, depending on the data provided.


NOTE: A Salesforce upsert should include an ID field that maps to the selected External ID in Salesforce.  If the ID field source record is populated with the Salesforce External ID, the record is updated in Salesforce. IF the ID field is blank, a new record is inserted into Salesforce. 

The wizard takes you through a series of screens, gathering the information it requires to create the operation in the current project. It follows these steps:

Table of Contents
excludeCreating a Salesforce.*Operation|^Start.*

Multiexcerpt include
PageWithExcerptSalesforce Org Wizard

Start the Wizard

Multiexcerpt include
PageWithExcerptSalesforce Org Wizard

  • To start the wizard, click the Salesforce Upsert button in the Jitterbit Connect Wizard menu, which opens the wizard.

Salesforce Login

Multiexcerpt include
PageWithExcerptSalesforce Query Wizard

Select the Salesforce Object

  • On the Object screen you specify the Salesforce Object and the External ID Field that the operation will use.
  • Simplify your view by typing the first few letters of an object's name in the Filter text entry box, or click the Objects to show dropdown menu and select from either Standard Common ObjectsAll Custom Objects, or All Objects.

  • Select the desired Salesforce Object:

Select an External ID Field

  • Click the Select Field… button to select an external ID field. In this example, the Account object and then the Id field were selected: 
WARNING: The field used as the external ID should have a unique value for each record. If you have multiple records with the same external ID value, an error response from Salesforce will be returned and the upsert will fail for the records with duplicate IDs.
  • Click Next to move to the Source screen.

Define the Source


Select Where Your Source Data Comes From

The source is the location of the data to be used by the operation.

  • If a File Source (Local File, FTP Site, File Share, or Temporary Storage):
    • What is the file type: text, XML, or JSON?
    • What is the file format structure: CSV or delimited?
    • What is the field format schema?
    • Is validation of the source file contents required? (If your source is a flat text file, you can optionally add row and field validation.)
  • If a Database Source, what is the connection information and SQL to retrieve the data?
  • If an LDAP Source, what are the object classes, attributes, and search parameters to retrieve the data?

The screens presented vary depending on your answers to these questions.

If you prefer, you can instead add a source later in your development of the project. For details on the different sources, see the documentation on Sources

NOTE: The screenshots shown may vary slightly from what is displayed when you use the wizard, as they are based on one of the wizards. The steps for configuring a source are the same for all Salesforce wizards.

Select one of:

  • An existing Source Type from the dropdown menu (one of Local File, FTP Site, File Share, Temporary Storage, Database, HTTP, LDAP, or None); or 
  • Click the Select or Create New button to create a new Source of the currently selected type; or
  • Choose None if you intend to provide explicit values for the data that do not come from other Sources.

Creating A New Source

To create a new Source, select the Create New… option from the dropdown menu. The New Source fields display. For example, when creating a new Local File Source, you will see fields similar to these:


NOTE: The type of source selected will determine the parameters to enter. See the documentation on Sources for details.

File Sources

For file sources (Local File, FTP Site, File Share, or Temporary Storage), you need to specify or create a source and then specify or create a file format to use with that source. If the file suffix cannot be used to determine the file type, you will be prompted to confirm the file and the file type.

Local File

NOTE: If you are creating a local file source for the first time, you must first enable local file locations in each Jitterbit Private Agent configuration. (A Local File can be used only with Private Agents.)
  • Specifying a Local File as a source:

  • Confirming selected file after reviewing the first ten lines of the file:

FTP Site, File Share, or Temporary Storage

  • Specifying an existing FTP Site as a source:
  • Click the Next button to move to the Confirm File Type screen.

Confirm File Type

  • If the file type cannot be confirmed based on the filename suffix, you will be asked to confirm the type. Adjust as required:
  • If the filename can be confirmed based on the filename suffix, you will be asked to select the options for creating a file format:
  • If you select the Review File Format, the Next button to move to the Select File Format screen. Otherwise, click the Next button to move to Create a Schedule and Set Options.

Select File Format

  • You can either select an existing File Format or create a new one.
  • To select an existing File Format, select the name from the dropdown:
  • To create a new file format, select Create New from the dropdown menu, which expands the screen to display the File Format fields. The example below shows the creating of a new File Format for a simple Text Document definition:

  • Complete the field and controls:
    • Name: Enter the name of the new file format
    • To Create Manually:
      • Select Document Type: Specify the document type as either Simple or Complex
      • Select Document Format: Specify as either Character Delimited or Fixed Field Widths
      • Create Manually: For details on creating the file format manually, see these instructions on Defining File Formats
    • To create From Sample File:
      • Click Create From File to open a dialog to specify the file structure using a file as a template
  • In this example, the Create From File was clicked and a CSV file was specified to use as a template:
  • Complete the fields and controls:
    • Template file type: Use the dropdown to select a template file type
    • Delimiter: Defaults to a comma delimiter
    • Select a template file: Select a template file from the dropdown, enter a path, or click the Browse button to navigate to a file to use as a template
    • File content: An auto-populated window showing a preview of the file contents
  • When you click OK, the Source screen changes to show the new File Format, with its Delimiter & QualifierValidation, and Segment Properties sections:
  • See Defining File Formats for additional information, including row and field validation for simple (flat) text file formats.

Review the File Format Structure

  • Click the Review Structure button in the lower left corner of the screen. A dialogue displays the fields you have selected for your upsert:
  • If the structure needs correction, edit the structure in the Define Segment Properties section before continuing.
  • If all elements are correct, click Next to continue to move to Create a Schedule and Set Options.

Database Source

  • Choose to enter the required SQL either manually or using the wizard:
  • Manually entering the SQL statement and then using the Check Syntax button:
  •  Using the wizard, specify the tables to use:
  • Using the wizard, specify the SQL Where clause to use:

LDAP Source

  • Specifying an LDAP Source:
  • Selecting the Object Class(es):

  • Selecting the Attributes:
  • Defining the Search Parameters:
  • When finished, click the Next button to move to Create a Schedule and Set Options.

Create a Schedule and Set Options

Multiexcerpt include
PageWithExcerptSalesforce Query Wizard

  • Click the Response Option checkbox if you need to interact with the response from Salesforce and want to map information directly from that response:

  • When finished, click Next to move to the Summary screen.

Summary Screen

On the Summary, you can edit the Name given to the wizard and specify whether to use the wizard's Automapper to map the data:

  • Click Map & Finish to complete the wizard.
  • If you need to create or approve a transformation mapping, you will be taken to that screen.
  • Otherwise, the design items for your upsert will be created and become visible in the Project Items panel on the left side of the screen and you will be taken to the operation's Salesforce Upsert page.

Transformation Mapping

If you chose Select an existing File Format (or created a new one) in the Target screen of the wizard, the transformation mapping appears in your work area.

Multiexcerpt include
PageWithExcerptSalesforce Query Wizard

Completed Salesforce Upsert

  • Once completed, you will be taken to the summary screen for the new Salesforce Upsert.
  • You can return to this summary page by finding its operation name under Jitterbit Connect in the Project Items panel.
  • You can modify any of the design items in your project such as Salesforce Login, External ID field, Read data from, MappingsOperation, and Run on Schedule by clicking their adjacent Edit button.
  • The Run Upsert, Test Upsert, Result History, and Delete button functions are described below in Deploy the Project and Run the Operation
  • Advanced Options including  include operation options such as chunking and field truncation. They are covered below in Advanced Options.

Advanced Options

These advanced options are available for a Salesforce Upsert:


File Options

  • Read as UTF-8: Select to read the source file as UTF-8 character encoding.
  • Date Options: Displays a dialog to set the date options for the source. See the Salesforce Advanced page.
  • Source file has a header: Select to indicate if there is a header and ignore it as not data.
  • Start at data row: Gives the row number of the first row of the source file to be considered as data.

Operation Options

  • Retry Policy: Displays a dialog to set the retry policies. See the Salesforce Advanced page.
  • Chunking settings: Displays a dialog to set the chunking settings. By default, chunking is enabled with a chunk size of 200 and a maximum number of 2 threads. See the Salesforce Advanced page.
  • Insert null values: If selected, allows the insertion of null values into a record.
  • Compress: By default, compression is turned on.
  • Allow field truncation: If selected, if a value for certain Salesforce datatypes is too large, the value is truncated; otherwise, too large values raise an error instead.
  • All or none: If selected, any failed records in a call cause all changes for the call to be rolled back.
  • Duplicate Records Rules:
    • Allow save: If selected, allows the saving of duplicate records, bypassing any Salesforce alerts.
    • Include record details: If selected, returns fields and values for records detected as duplicates; otherwise, only record IDs are returned.
    • Run as current user: If selected, the sharing rules for the current user are enforced.
  • Ownership Options: Displays a dialog to set the ownership options. See the Salesforce Advanced page.

Additional operation options for writing success and failure records are described on the Salesforce Advanced page.

Deploy the Project and Run the Operation

Multiexcerpt include
PageWithExcerptSalesforce Query Wizard

The Result History button will give historical run information once it is available, if a Private Agent is used.

titleOn This Page
Table of Content Zone

Table of Contents

titleRelated Articles
Content by Label
cqllabel = "salesforce" and space = "DOC"
titleRelated Topics
Content by Label
cqllabel in ("sf-connect-overview","template-overview") and space = "DOC"


Last updated: