Importing Complex Records to Salesforce (V2)

Overview

This task updates or inserts multiple records of various types in Salesforce and establishes relationships between them.

For example, you can use this task to upload opportunities and opportunity line items and link them to a specific account and pricebook.

Matching

Existing records are matched with those provided in the input file based on the Salesforce field specified as the key field.

If no key field is specified, the Id field is used for matching. When a match is found, the existing record is updated; otherwise, a new record is inserted.

The task also supports value lookups in existing Salesforce records based on fields of your choice.

For instance, when uploading an opportunity, if you only know the account name but need the account ID, you can use a lookup to find the corresponding ID based on the specified name.

Caching

The caching logic is available as an optional setting for this task, allowing you to optimize performance when performing lookups during the import process.

The available caching settings and their descriptions are outlined in this article.

XML

Settings

Salesforce Connection

Required
The Salesforce connection to use, see Connecting to Salesforce

Salesforce (Bulk) Connection

Optional
The Bulk Salesforce connection to use, see Connecting to Salesforce (Bulk). Setting a bulk connection will allow the task to automatically switch to the bulk API when there's a large amount of data to upload to Salesforce. This will increase the speed of the upload, and reduce the number of API requests it uses.

Fail File

Required
The file to output any records to that fail to import to Salesforce.

Input File

Required
The XML file containing the records to import to Salesforce. A sample of the XML format is shown below.

Success File

Required
The file to output successfully imported records to.

Bulk Batch Size

Required
The maximum number of records to send to the bulk API in a single batch. The value must be between 1 and 5000. Defaults to 5000.

This setting is only applicable when a bulk connection has been provided via the Salesforce (Bulk) Connection setting, and the number of records to insert or update exceeds the value in the Bulk Threshold setting.

Bulk Concurrency Mode

Required
The concurrency mode for bulk jobs. Use serial mode if you experience errors related to locking.

This setting is only applicable when a bulk connection has been provided via the Salesforce (Bulk) Connection setting, and the number of records to insert or update exceeds the value in the Bulk Threshold setting.

Bulk Threshold

Required
The number of records that will prompt the task to use the bulk API instead of the REST API. Defaults to 1000.

Operation Type

Required
The operation to perform against Salesforce, when an operation hasn't been specified in the input file. The following options are available:

  • Insert - Only create new records in Salesforce
  • Update - Only update existing records in Salesforce
  • Upsert - Create new or update existing records in Salesforce. This is the default option.

REST Batch Size

Required
The maximum number of records to send to the REST API in a single batch. The value must be between 1 and 200. Defaults to 200.

Cache Type

Optional
Specifies how and where lookup values will be cached. The following options are available:

  • Dynamic: Automatically switches between cache types based on the number of records being uploaded. Uses the Dynamic Threshold setting to determine when to switch.
  • Database: Stores all cached lookup values in a database.
  • Memory: Stores all cached lookup values in memory.
  • Both: Stores cached lookup values in both memory and the database.

Dynamic Threshold

Optional
Defines the number of records that will cause the Cache Type to switch automatically from Both to Database. This setting is only applicable when the Cache Type is set to Dynamic.

Time to Live (Mins)

Optional
Specifies the duration (in minutes) that cached lookup values remain valid. This setting applies only when using Database caching.

Zynk Settings

See Common Task Settings

Examples

A sample input file containing an opportunity and 2 line items is shown below. For detailed information on the XML schema, see Salesforce Complex Object XML.

<?xml version="1.0"?>
<SalesforceObjects Type="Opportunity" Key="Name">
    <SalesforceObject Operation="Upsert">
        <Field Name="Name" Value="Order 12345" Truncation="Right" />
        <Field Name="CloseDate" Value="2023-02-14" />
        <Field Name="StageName" Value="closed won" PicklistValueCaseSensitive="false" />
        <LookupField Name="AccountId" Select="Id" From="Account" MatchType="Single">
            <WhereField Name="Name" Value="19 Computing" />
        </LookupField>
        <LookupField Name="Pricebook2Id" Select="Id" From="Pricebook2">
            <WhereField Name="Name" Value="Standard Price Book" />
        </LookupField>
        <RelatedObject Type="OpportunityLineItem" Key="Id" Operation="Upsert">
            <LookupField Name="Id" Select="Id" From="OpportunityLineItem">
                <WhereField Name="OpportunityId" Value="{ParentId}" Comparison="Equals" />
                <LookupField Name="PricebookEntryId" Select="Id" From="PricebookEntry" MatchType="Index" MatchIndex="0">
                    <WhereField Name="Pricebook2.Name" Value="Standard Price Book" Comparison="Equals" />
                    <WhereField Name="CurrencyIsoCode" Value="GBP" Comparison="Equals" />
                    <WhereField Name="Product2.ProductCode" Value="IPHONE4" Comparison="Equals" />
                </LookupField>
            </LookupField>
            <Field Name="Description" Value="iPhone 4" />
            <Field Name="OpportunityId" Value="{ParentId}" />
            <Field Name="Quantity" Value="1" />
            <Field Name="UnitPrice" Value="250" />
            <LookupField Name="PricebookEntryId" Select="Id" From="PricebookEntry" MatchType="Index" MatchIndex="0">
                <WhereField Name="Pricebook2.Name" Value="Standard Price Book" Comparison="Equals" />
                <WhereField Name="CurrencyIsoCode" Value="GBP" Comparison="Equals" />
                <WhereField Name="Product2.ProductCode" Value="IPHONE4" Comparison="Equals" />
            </LookupField>
        </RelatedObject>
        <RelatedObject Type="OpportunityLineItem" Key="Id" Operation="Upsert">
            <LookupField Name="Id" Select="Id" From="OpportunityLineItem">
                <WhereField Name="OpportunityId" Value="{ParentId}" Comparison="Equals" />
                <LookupField Name="PricebookEntryId" Select="Id" From="PricebookEntry" MatchType="Index" MatchIndex="0">
                    <WhereField Name="Pricebook2.Name" Value="Standard Price Book" Comparison="Equals" />
                    <WhereField Name="CurrencyIsoCode" Value="GBP" Comparison="Equals" />
                    <WhereField Name="Product2.ProductCode" Value="00299" Comparison="Equals" />
                </LookupField>
            </LookupField>
            <Field Name="Description" Value="WIHA Screwdriver" />
            <Field Name="OpportunityId" Value="{ParentId}" />
            <Field Name="Quantity" Value="1" />
            <Field Name="UnitPrice" Value="0.01" />
            <LookupField Name="PricebookEntryId" Select="Id" From="PricebookEntry" MatchType="Index" MatchIndex="0">
                <WhereField Name="Pricebook2.Name" Value="Standard Price Book" Comparison="Equals" />
                <WhereField Name="CurrencyIsoCode" Value="GBP" Comparison="Equals" />
                <WhereField Name="Product2.ProductCode" Value="00299" Comparison="Equals" />
            </LookupField>
        </RelatedObject>
    </SalesforceObject>
</SalesforceObjects>