Salesforce Bulk Upsert activity¶
Introduction¶
A Salesforce Bulk Upsert activity updates a large number of existing records and inserts a large number of new records in a Salesforce endpoint and is intended to be used as a target to consume data in an operation. After configuring a Salesforce connection, you can configure as many Salesforce activities as you like for each Salesforce connection.
The Bulk Upsert activity is faster and scales better than a non-bulk Salesforce Upsert activity, but should be used only if you do not need to use a transformation to change data prior to reaching its target. (Salesforce bulk activities cannot be used with transformations.)
The Bulk Upsert activity requires the use of an external ID field to (1) insert records if they do not already exist and (2) update records if they already exist. For information on creating an external ID field in Salesforce, see Create a Salesforce external ID for Jitterbit. If instead you want to bulk insert new records only, or if you want to bulk update existing records based on the ID of the object in Salesforce, use a Salesforce Bulk Insert or Bulk Update activity.
The Salesforce connector supports Salesforce Bulk API. For more information, see Prerequisites and supported API versions.
Create a Salesforce activity¶
An instance of an activity is created from a connection using an activity type.
To create an instance of an activity, drag the activity type to the design canvas or copy the activity type and paste it on the design canvas. For details, see Creating an activity instance in Component reuse.
An existing activity can be edited from these locations:
- The design canvas (see Component actions menu in Design canvas).
- The project pane's Components tab (see Component actions menu in Project pane Components tab).
Configure a Salesforce Bulk Upsert activity¶
Follow these steps to configure a Salesforce Bulk Upsert activity:
- Step 1: Enter a name and select an object Provide a name for the activity and select an object to be used when bulk upserting data.
- Step 2: Specify an external ID Select an existing Salesforce field that you want Harmony to use as the external ID to associate records.
- Step 3: Provide the response schema Upload or select a CSV file. This will provide the schema to be used in the final step.
- Step 4: Map headers Map the source file headers provided from the CSV file with the desired Salesforce fields of the records to be bulk upserted.
Step 1: Enter a name and select an object¶
In this step, you provide a name for the activity and select an object to be used when bulk upserting data.
-
Name: Enter a name to use to identify the Salesforce Bulk Upsert activity. The name must be unique for each Salesforce Bulk Upsert activity and must not contain forward slashes (
/
) or colons (:
). -
Select the object reference: Use the dropdown to select a Salesforce standard or custom object to bulk upsert data. Enter any column's value into the search box to filter the list of objects. The search is not case-sensitive.
Note
If the dropdown does not populate with available objects, the Salesforce connection may not be successful. Ensure you are connected by reopening the connection and retesting the credentials.
-
Refresh: Click the refresh icon to reload objects from the Salesforce endpoint. This may be useful if you have recently added objects to Salesforce.
-
Save & Exit: If enabled, click to save the configuration for this step and close the activity configuration.
-
Next: Click to temporarily store the configuration for this step and continue to the next step. The configuration will not be saved until you click the Finished button on the last step.
-
Discard Changes: After making changes, click to close the configuration without saving changes made to any step. A message asks you to confirm that you want to discard changes.
Step 2: Specify an external ID¶
In this step, you select an existing Salesforce field that you want Harmony to use as the external ID to associate records.
-
External ID: Use the dropdown to select the existing Salesforce field that you want Harmony to use as the external ID to associate records. For information on creating an external ID field in Salesforce, see Create a Salesforce external ID for Jitterbit.
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 bulk upsert will fail for the records with duplicate IDs.
-
Back: Click to temporarily store the configuration for this step and return to the previous step.
-
Next: Click to temporarily store the configuration for this step and continue to the next step. The configuration will not be saved until you click the Finished button on the last step.
-
Discard Changes: After making changes, click to close the configuration without saving changes made to any step. A message asks you to confirm that you want to discard changes.
Step 3: Provide the response schema¶
In this step, upload or select a CSV file. The CSV file will provide the schema to be used in Step 4: Map headers.
-
Provide request schema: An uploaded or existing CSV file defines the schema that is used in the request. This schema is used as part of the Salesforce bulk activity for creating mappings in the next step. Select from one of two options below.
Note
Schemas for Salesforce bulk activities are always part of the activity and can never be defined in a transformation, as transformations cannot be used in an operation that has a Salesforce bulk activity.
-
Use saved schema: Choose this option to select an existing schema that has previously been defined in the current project.
-
Saved schemas: Use the dropdown to select from an existing schema to reuse.
-
View schema: After an existing uploaded schema is selected, you can view the schema directly within the text area below the dropdown. Though a saved schema is not editable, this text area can be copied using
Control+C
(Windows or Linux) orCommand+C
(macOS). This text area is only for the display of existing uploaded schemas and not for flat, hierarchical, or mirrored custom schemas. -
Validation: Validation information is provided below the text area and is based on the file extension of the saved schema.
- Provide new schema: Choose this option to define a new schema by uploading a file or manually entering one into the text area.
-
Schema name: Enter a name for the schema into the upper text box, including the file extension. If no file extension is provided, the file is treated as CSV by default. If you are uploading a file, you can leave this blank, as the name is populated once the file is loaded.
-
Upload File: Click this button to open a dialog where you can load a schema from a file that is accessible from the current machine:
-
File: Use the Browse button to browse for a flat file with a header that has not yet been used in the current project. Files up to 5 MB in size can be uploaded.
Warning
If you try to upload a file with the same name as an existing file already defined in the project, a dialog asks if you want to overwrite the existing file. If you click Continue, the file will be replaced with the new file with the same name in all places where it is used in the project. If you don't want to overwrite the file, click Cancel and then manually modify the file so it has a name that is not already being used, then try to upload it again.
-
Load: Click this button to load the schema from the file. Note that some data may be converted during processing as described in Schema processing.
-
Cancel: Click Cancel to close the Upload Schema File dialog without saving.
-
-
View/edit schema: After a schema is loaded, you can view or edit it directly within the text area below the Upload File button. Another option is to manually enter or paste a schema into this area without loading a schema from a file.
-
Validation: As you edit a schema, validation information will be provided below the text area, with any errors reported one line at a time. That is, after resolving an error on one line, additional syntax errors to resolve may be reported for subsequent lines. Validation is based on the file extension of the provided schema.
-
-
-
Back: Click to temporarily store the configuration for this step and return to the previous step.
-
Next: Click to temporarily store the configuration for this step and continue to the next step. The configuration will not be saved until you click the Finished button on the last step.
-
Discard Changes: After making changes, click to close the configuration without saving changes made to any step. A message asks you to confirm that you want to discard changes.
Step 4: Map headers¶
In this step, you map the source file headers from the CSV file provided in Step 3: Provide the response schema to the desired Salesforce fields of the records to be bulk upserted.
-
Map Headers: This step is used to map fields by column in the source file to those in the Salesforce bulk target activity. To complete a mapping, drag a source field on the left to a target field on the right. When fields are mapped, the background becomes orange and a line is drawn between the mapped fields. To remove a mapping, click either the source field or target field.
-
Source file Headers: The left side shows the headers for the columns in the file provided in the previous step.
-
Search: Enter any column's value into the search box to filter the list of headers. The search is not case-sensitive.
-
Import Mapping: To import a mapping that has previously been exported, click the Import Mapping link, then provide input in the dialog:
-
File Type: Use the dropdown to select the format of the mapping file:
- JDL: Select JDL to use a file that has been exported from a Design Studio bulk process operation (from the Design Studio option to Save Mappings to File described in Transformation mapping in Salesforce bulk process wizard for upsert action).
- JSON: Select JSON to use a file that has been exported from Integration Studio using the Export Mapping link described below.
-
File: Click the Browse button on the right to select a file that contains the mapping.
-
Upload: After selecting a file, click Upload to upload the mapping.
Warning
The uploaded mapping overwrites any existing mappings, if present.
-
Cancel: Click Cancel to close the import dialogue without uploading a mapping.
-
-
Export Mapping: To export an existing mapping, click the Export Mapping link. This initiates the download process in your browser. The exported file is in JSON format. Each field mapping includes the source field name, target field name, and source index.
Note
Exported bulk activity mappings cannot be imported as transformation mappings and can be imported only using the Import Mapping link described above.
-
-
Salesforce Fields: The right side shows the column names in Salesforce that are available to be mapped to.
- Search: Enter any column's value into the search box to filter the list of headers. The search is not case-sensitive.
- Automap: Click the Automap link to map source and target field names that are exact match (regardless of case) and have identical data types. Fields that are automapped are in addition to any existing mappings, which are left in place.
- Start Over: Click the Start Over link to clear all mappings.
- Back: Click to temporarily store the configuration for this step and return to the previous step.
- Finished: Click to save the configuration for all steps and close the activity configuration.
- Discard Changes: After making changes, click to close the configuration without saving changes made to any step. A message asks you to confirm that you want to discard changes.
-
Next steps¶
After configuring a Salesforce Bulk Upsert activity, you can use it within an operation as described below. After running an operation containing a Salesforce activity on a private agent, you can download the operation's success and failure files.
Complete the operation¶
After configuring a Salesforce Bulk Upsert activity, complete the configuration of the operation by adding and configuring other activities or scripts as operation steps. You can also configure an operation's operation settings, which include the ability to chain operations together that are in the same or different workflows.
Once a Salesforce Bulk Upsert activity has been created, menu actions for that activity are accessible from the project pane in either the Workflows or the Components tabs, and from the design canvas. See Activity actions menu for details.
Salesforce Bulk Upsert activities can be used as a target with this operation pattern:
A Salesforce activity can be used as an operation step in only a single operation. That is, you cannot reference the same activity multiple times within other operations. Instead, you can make a copy of a Salesforce activity to use elsewhere (see Component reuse).
Other patterns are not valid using Salesforce Bulk Upsert activities. See the validation patterns on the Operation validity page.
In addition, the file-based source used in the operation must be using a flat file format with a header and only these data types:
- Base64
- Boolean
- Date formats
- Double
- Integer
- Salesforce ID
- String
Operations that use Salesforce activities can also have operation actions configured to trigger on a SOAP fault — an error resulting from an incorrect message format, header processing, or incompatibility. Operation actions can be configured to run an operation or send an email after a SOAP fault occurs. For instructions on triggering an action on SOAP fault, refer to Operation actions.
To use the activity with scripting functions, write the data to a temporary location and then use that temporary location in the scripting function.
When ready, deploy and run the operation and validate behavior by checking the operation logs.
View success and failure files¶
If you are running an operation containing a Salesforce activity on a private agent, success and failure files are available for download in the Runtime Operations page of the Management Console. Select the relevant operation in the Runtime Operations table and click the Activity Logs tab in the bottom section of the screen to display download links for the files if available:
-
Download Success File: If you are running the operation on a private agent, click the Download link to save the success records as a CSV file.
-
Download Failure File: If you are running the operation on a private agent, click the Download link to save the failure records as a CSV file.
Note
By default, success and failure 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 [Resultfiles]
section in the jitterbit.conf
file. You can also change the success and failure file retention rules by editing the Jitterbit file cleanup service rules for private agents.
Activity log downloads are disabled for cloud agents. If the links are visible, you will receive an error message if you attempt a download.