This page describes how to create a Salesforce Bulk Process Upsert action using the Salesforce Bulk Process Wizard in Jitterbit Harmony 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.
Selecting the Salesforce Object
On the Object screen, select the Salesforce object and the External ID Field that the operation will use.
NOTE: You can 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 Objects, All Custom Objects, or All Objects.
To select an External ID Field, click the Select Field button. In this example, the Account object and then the Id field were selected:
NOTE: 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 OK, then click Next to move to Defining the Source.
Defining 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.
Creating a New Source
To create a new source, select the New Source option from the dropdown menu:
NOTE: The type of source selected will determine the Connection Parameters to enter. See Sources for details.
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.
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.)
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 Harmony 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.
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.
Creating a Schedule and Selecting 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.
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 Deploying the Project and Running 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.
These advanced options are available for a Salesforce Bulk Upsert action:
- 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.
- 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.
Deploying the Project and Running 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.
Deploying 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 Jitterbit 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.
Running 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 Operations 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 Operations for additional information on creating, deploying, and running operations.
Viewing 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
- Open External Program: This option is currently not available.
NOTE: The success and failure files are available for viewing from the Private Agent for 14 days by default. The files are automatically deleted from the Private Agent after 14 days by the Jitterbit File Cleanup Service. The number of days the files are saved can be changed by editing the
jitterbit.conf file in the
[ResultFiles] section (see Editing the Configuration File). You can also change the success and failure file rules by Editing the Jitterbit File Cleanup Service Rules for Private Agents.