Salesforce bulk process wizard for upsert action in Jitterbit Design Studio

Introduction

This page describes how to create a Salesforce Bulk Process Upsert action using the Salesforce Bulk Process Wizard in Jitterbit Design Studio. The Salesforce Bulk Process Upsert action allows you to either insert multiple records or (in the case of a record already existing) update an existing record, through a connected Salesforce instance. An Upsert action updates or inserts records, depending on the data provided.

The process for the Upsert Bulk Process action is slightly different than the process for Query, insert, update, delete, or hard delete Bulk Process actions. The Upsert Bulk Process action requires you to select an external ID field for the selected Salesforce object. Query, Insert, Update, Delete, and Hard Delete Bulk Process actions do not require an external ID field and do not include this step.

Before moving through these steps, see Salesforce bulk process wizard for instructions on starting the Salesforce Bulk Process Wizard.

Select the Salesforce object

On the Object screen, select the Salesforce object and the External ID Field that the operation will use.

To select an External ID Field, click the Select Field button. In this example, the Account object and then the Id field were selected:

Click OK, then click Next to move to Define the source.

Define the source

Select where your source data comes from

The source is the location of the data to be used by the operation. For the Salesforce Bulk Process Wizard, the source needs to be a flat file source with a header. Databases are not supported. For the File source select Local File, FTP Site, File Share, or Temporary Storage.

Since the source will need to be a flat file for the Salesforce Bulk Process Wizard, you can optionally add row and field validation. If you prefer, you can instead add a source later in your development of the project. For details on the different sources, see Sources.

Select one of the following:

• An existing source Type from the dropdown menu (one of Local File, FTP Site, File Share, Temporary Storage, or HTTP).
• Select Create New to create a new source of the currently selected type.

Create a new source

To create a new source, select the New Source option from the dropdown menu:

File sources

For file sources (Local File, FTP Site, File Share, or Temporary Storage), select or create a source and then select or create a file format to use with that source.

Local file

If you select a Local File as a source, click Browse to select a file. Alternatively, if you'd like to use a local file that has been previously used with Jitterbit Design Studio, click Select an Existing Local File Source and use the dropdown menu to select a previously used file.

Confirm the selected file after reviewing the first ten lines of the file:

Click Continue to move to the Mappings screen.

FTP site, File Share, or Temporary Storage

If you'd like to use an existing FTP Site as a source, use the Type dropdown menu to select your FTP Site. Otherwise, select Create New in the dropdown menu and populate the Connection Parameters.

Select sample file

Browse your computer and select a sample file that contains the same format as the file you'd like to send to Salesforce. Design Studio will use this information on the Mappings screen.

Click Next to move to the Mappings screen.

Transformation mapping

Map headers from the source file to the corresponding Salesforce fields. Aside from the headers, Bulk Process does not involve any other mappings.

You can map:

• By dragging and dropping a Source File Header to a Salesforce Field.

• By selecting Source and Salesforce fields together and then clicking the Map button.

• The Auto Map button maps based on matching names between the Source File Headers and the Salesforce Fields.

• The Import Mappings from File button imports a previously saved set of mappings from a file.

• The Save Mappings to File button saves all of the mappings to a local file.

• The Map button maps between selected source and target fields.

• The Remove button removes a selected mapping.

• The Start Over button deletes all of the mappings and starts over.

• When finished, click Next to move to Create a schedule and set options.

Create a schedule and select options

Creating or setting a schedule is optional and can be done at a later time. For more details on scheduling, see Schedules. You can edit an existing schedule by opening it in the Schedules category of the project items panel and making any desired adjustments. You can use this wizard screen to either add a schedule to an unscheduled operation or open the operation under the project items panel and make the appropriate adjustments.

• Set the Occurrence, Daily Frequency (hours or minutes), and Duration of the operation.
• When setting Duration, be aware that Starting at and Ending at dates in a schedule are inclusive.
• To display these options, open the disclosure triangles beside Occurrence, Daily Frequency, and Duration.
• When finished, click Next to move to Summary screen.

Summary screen

On the Summary screen, you can edit the name given to the wizard:

Click Finish to complete the wizard.

Completed Salesforce bulk process

Once completed, you will be taken to the Summary screen for the new Salesforce Bulk Process. 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, Mappings, Read Data From, Operation, and Run on Schedule by clicking the adjacent Edit.
• The Run Bulk Upsert, Result History, and Delete button functions are described below in Deploy the project and run the operation (The actual labels and available buttons will vary depending on the particular Bulk Process wizard used. This example shows the Bulk Insert wizard).
• Advanced Options 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 Bulk Upsert action:

File options

• Read as UTF-8: Select to read the source file as UTF-8 character encoding.
• Write as UTF-8: Select to write the target file as UTF-8 character encoding.
• Date Options: Displays a dialog to set the date options for the source. See the Salesforce advanced page.
• Start at Data Row: Gives the row number of the first row of the source file to be considered as data.

Operation options

• Batch Settings: Displays a dialog to set the bulk settings. See the Salesforce advanced page.
• Serial Mode: If selected, allows the insertion of null values into a record.
• Compress Data: By default, compression is turned on.
• Chunking is not available for Bulk Process operations. See Batch Settings on the Salesforce advanced page instead.

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

Deploy the project and run the operation

Once you have configured the Bulk Process action, you can deploy and run the operation. You can also view success and failure files if using private agents.

Deploy the project

Deploying a project before running is not required as it will automatically be deployed if needed.

To deploy the project, do one of the following:

• Click the Deploy button on the toolbar.

• On the project items panel right-click on the Name of the project just created, and then click Deploy on the resulting dropdown menu.

• Click Operations at the top of the project items panel and then click Deploy on the resulting dropdown menu.

The project deploy process will begin sending the project to Harmony, and a progress message will appear.

• To run the progress message in the background, click Run in Background.

• To cancel the deploy process, click Cancel, which returns you to the previous screen.

The operation is now complete and deployed.

Run the operation

Click the Run Bulk Upsert button to place the operation in the queue for execution.

If the project has not already been deployed, or has been changed since the last deploy, it will automatically be deployed. See Create an operation for additional information on creating, deploying, and running operations.

• The Operation Monitor displays at the bottom of the screen, tracking the status, time received, time started, and the time the operation completed processing.

• When the operation completes processing, the Result dialog will display the time of completion, the status, the number of records that successfully processed, and the number of records that failed to process. The View Success File and View Failure File buttons are described below.

Click the Result History button to display a list of recent activities including the time completed, status, the number of records processed successfully, and the number of records that failed to process. Select a result in the list to enable the View Success File and View Failure File buttons, which are described below.

Click the Delete button to delete the operation from the project.

• The Confirm Delete dialog window will display. Click Delete to confirm and delete the operation.
• The Delete Wizard Items dialog will display the associated operation components.
  • Select Yes to delete the associated wizard objects in addition to the insert operation.
  • If you select No, the wizard objects remain available within the project. Only the insert operation is deleted.
  • Selecting Cancel cancels the deletion of the insert operation and the associated wizard objects.

See Create an operation for additional information on creating, deploying, and running operations.

View success and failure files

Viewing success and failure files is available if you are running operations on a private agent. The View Success File and View Failure File buttons are available after you click the Run button or the Result History button as described above and then select one of the results. This is an example of the Result History dialog, showing the buttons and a selected result:

• View Success File: If you are running the operation on a private agent, selecting the View Success File button displays the first 100 records that successfully processed.
• View Failure File: If you are running the operation on a private agent, selecting the View Failure File button displays the first 100 records that failed to process.

In this example, three records are shown:

• Copy File To: Saves the success or failure records to a CSV file with the default file name salesforce.csv.
• Open External Program: This option is currently not available.