Salesforce Complex Object XML

Tasks

Importing Complex Records to Salesforce (V2)

This task will create or update multiple records of different types in Salesforce, and create relationships between them. The example below shows how to upload opportunities and opportunity line items, and link them to a particular account and price book.

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>

In each of the following sections most of the XML has been omitted to make the samples easier to read. The whole structure of the SalesforceObjects schema is used below as a reference of where fields should be in the object model.

SalesforceObjects

The SalesforceObjects element represents a collection of objects to upload to Salesforce. This element is the root of the XML document.

XML Field	Example	Field Type	Input	Description
@Type	Opportunity	string	Required	The type of objects contained within the collection. This should correspond with the API name of an object in Salesforce.
@Key	Name	string	Optional	Specify the Salesforce API name of a field to use as the key. Defaults to Id if not specified. The key field will be used to match each SalesforceObject to an existing record in Salesforce, so long as a `Field` child element is provided with the same name. If a match is found, the existing record will be updated, otherwise a new record will be created.
SalesforceObject	N/A	SalesforceObject	Optional	A record to upload to Salesforce. Multiple `SalesforceObject` elements can be included in the `SalesforceObjects` collection. See SalesforceObject for more info.

<?xml version="1.0"?>
<SalesforceObjects Type="Opportunity" Key="Name">
    <SalesforceObject>
        <!-- See SalesforceObject below -->
    </SalesforceObject>
</SalesforceObjects>

SalesforceObject

The SalesforceObject element represents an individual record to insert or update in Salesforce. It can contain multiple fields, lookups and other related objects.

XML Field	Example	Field Type	Input	Description
@Operation	Insert	enum	Optional	The type of operation to perform against Salesforce. The available options are Insert, Update and Upsert. Will default to the option selected in the task settings if not specified.
Field	N/A	Field	Optional	Represents a field that should be set to a pre-determined value in Salesforce. Multiple `Field` elements can be provided. See Field for more info.
LookupField	N/A	LookupField	Optional	Represents a field where the value should be looked up in Salesforce. Multiple `LookupField` elements can be provided. See LookupField for more info.
RelatedObject	N/A	RelatedObject	Optional	Represents a child record that should be uploaded to Salesforce. Multiple `RelatedObject` elements can be provided. See RelatedObject for more info.

<?xml version="1.0"?>
<SalesforceObjects Type="Opportunity">
    <SalesforceObject Operation="Insert">
        <Field Name="Name" Value="Order 12345" />
        <LookupField Name="AccountId" From="Account">
            <WhereField Name="Name" Value="19 Computing" />
        </LookupField>
        <RelatedObject Type="OpportunityLineItem">
            <!-- See RelatedObject below -->
        </RelatedObject>
    </SalesforceObject>
</SalesforceObjects>

Field

The Field element represents a field that should be set to a pre-determined value in Salesforce.

XML Field	Example	Field Type	Input	Description
@Name	StageName	string	Required	The Salesforce API field name of the field to set in Salesforce.
@Value	Closed Won	string	Optional	The value to set the field to. Omit this attribute from the XML to set the value to null in Salesforce.
@Operation	Insert	enum	Optional	Insert will only set this field when creating a new record in Salesforce. Update will only set this field when updating an existing record in Salesforce. Upsert will set this field regardless. If not specified, it will default to 'Upsert'.
@Truncation	None	enum	Optional	When setting a text field in Salesforce, this attribute can be used to automatically truncate the value if it is too long. Valid values: None, Right, Left
@PicklistValueMatching	ApiName	enum	Optional	When setting a picklist field in Salesforce, this attribute is used to specify how to match the `@Value` provided to one of the picklist options in Salesforce. ApiName will match the Value to the picklist's API names. Value will match the Value to the picklist's display values. ApiNameThenValue will firstly try to match based on API name, then fall back to the value if no match is found. ValueThenApiName will firstly try to match based on value, then fall back to the API name if no match is found. If not specified, the matching will default to 'ApiName'.
@PicklistValueCaseSensitive	false	bool	Optional	When setting a picklist field in Salesforce, this attribute is used to specify whether the `@Value` provided should be matched on a case sensitive basis or not. Defaults to true if not specified.

<?xml version="1.0"?>
<SalesforceObjects Type="Opportunity">
    <SalesforceObject>
        <Field Name="StageName" Value="Closed Won" Operation="Insert" Truncation="None" PicklistValueMatching="ApiName" PicklistValueCaseSensitive="false" />
    </SalesforceObject>
</SalesforceObjects>

LookupField

The LookupField element represents a lookup for the value of a field from an existing object Salesforce. This is useful where you need to set a field to the same value as a field on another object in Salesforce. The example shown below will lookup the ID of the account with the name 'Test 123', and use this as the value for the AccountId field on an opportunity.

The criteria that should be used to search Salesforce is specified by child elements of the LookupField, so there must always be at least one child element. If multiple child elements are specified, only records which meet all of the conditions will be considered a match. The following child elements are supported:

WhereField - Used to search a particular field for a pre-determined value. In the example shown below, this is used to find accounts where the name equals "Test 123".
LookupField - Complex lookups across different types of object can be constructed by using further LookupField elements as children. In the example shown below, this is used to search the User object for the Id of the user with the name "John".

If there are multiple LookupField elements for the same field (i.e. where the Name attribute is the same), the task use the first one that finds a match in Salesforce. This can be used to match records which meet one condition or another.

XML Field	Example	Field Type	Input	Description
@Name	AccountId	string	Required	The API name of the field to set in Salesforce.
@Value	N/A	string	Optional	If a value is specified, this will be used instead of performing the lookup.
@Operation	Insert	enum	Optional	Insert will only set this field when creating a new record in Salesforce. Update will only set this field when updating an existing record in Salesforce. Upsert will set this field regardless. If not specified, it will default to 'Upsert'.
@Select	Id	string	Optional	The API name of the field containing the value to be returned by the lookup. If not specified, this will default to Id.
@From	Account	string	Required	The API name of the object to perform the lookup against.
@MatchType	Index	enum	Optional	The type of matching to perform against Salesforce. Single will return the first matching record, but will fail if more than one match is found. First will return the first matching record found. Last will return the last matching record found. Index will return the matching record from a specific index, as specified by the `@MatchIndex` attribute. Will default to 'Single' if not specified.
@MatchIndex	1	int	Dependant	The 0 based index of the record the lookup should return. Used in conjunction with the Index MatchType.
WhereField	N/A	WhereField	Dependant	Used to search a particular field for a pre-determined value. Multiple `WhereField` elements can be provided. See WhereField for more info.
LookupField	N/A	LookupField	Dependant	Complex lookups across different types of object can be constructed by using further `LookupField` elements as children. Multiple `LookupField` elements can be provided.

<?xml version="1.0"?>
<SalesforceObjects Type="Opportunity">
    <SalesforceObject>
        <!-- This will set the AccountId field on the opportunity to the Id of the account where the name is "Test 123" and the owner name is "John" -->
        <LookupField Name="AccountId" Operation="Insert" Select="Id" From="Account" MatchType="Index" MatchIndex="1">
            <WhereField Name="Name" Value="Test 123" Comparison="Equals" />
            <LookupField Name="OwnerId" Select="Id" From="User">
                <WhereField Name="Name" Value="John" Comparison="Equals" />
            </LookupField>
        </LookupField>
        
        <!-- This will set the Pricebook2Id to the Id of the price book called 'Retail', but if one doesn't exist, it will use the standard price book instead -->
        <LookupField Name="Pricebook2Id" Select="Id" From="Pricebook2">
            <WhereField Name="Name" Value="Retail" />
        </LookupField>
        <LookupField Name="Pricebook2Id" Select="Id" From="Pricebook2">
            <WhereField Name="IsStandard" Value="true" />
        </LookupField>
    </SalesforceObject>
</SalesforceObjects>

WhereField

The WhereField element is used as a child of a LookupField to search a particular field for a pre-determined value.

XML Field	Example	Field Type	Input	Description
@Name	Type	string	Required	The API name of the field the lookup should search in Salesforce.
@Value	Reseller	string	Required	The value the lookup should search for in Salesforce.
@Comparison	Equals	enum	Optional	The type of comparison to use when searching Salesforce. The available options are Equals, GreaterThan, GreaterThanOrEquals, LessThan, LessThanOrEquals, Like. Will default to 'Equals' if not specified.
@PicklistValueMatching	ApiName	enum	Optional	When searching a picklist field in Salesforce, this attribute is used to specify how to match the `@Value` provided to one of the picklist options in Salesforce. ApiName will match the Value to the picklist's API names. Value will match the Value to the picklist's display values. ApiNameThenValue will firstly try to match based on API name, then fall back to the value if no match is found. ValueThenApiName will firstly try to match based on value, then fall back to the API name if no match is found. If not specified, the matching will default to 'ApiName'.
@PicklistValueCaseSensitive	false	bool	Optional	When searching a picklist field in Salesforce, this attribute is used to specify whether the `@Value` provided should be matched on a case sensitive basis or not. Defaults to true if not specified.

<?xml version="1.0"?>
<SalesforceObjects Type="Opportunity">
    <SalesforceObject>
        <LookupField Name="AccountId" Select="Id" From="Account">
            <WhereField Name="Type" Value="Reseller" Comparison="Equals" PicklistValueMatching="ApiName" PicklistValueCaseSensitive="false" />
        </LookupField>
    </SalesforceObject>
</SalesforceObjects>

RelatedObject

The RelatedObject element represents an individual child record of the SalesforceObject it is placed in. To create the relationship between the two records, you need make sure you set the value of the field that links the child to it's parent. You can access the Id of the parent record using the {ParentId} variable, as shown in the sample XML below.

The RelatedObject element is itself a SalesforceObject, so it supports all of the attributes and child elements described in that section of the documentation.

XML Field	Example	Field Type	Input	Description
@Type	OpportunityLineItem	string	Required	The API name of the Salesforce object.
@Key	Id	string	Optional	Specify the Salesforce API name of a field to use as the key. Defaults to Id if not specified. The key field will be used to match each RelatedObject to an existing record in Salesforce, so long as a `Field` child element is provided with the same name. If a match is found, the existing record will be updated, otherwise a new record will be created.
@Operation	Upsert	enum	Optional	The type of operation to perform against Salesforce. The available options are Insert, Update and Upsert. Will default to the same value as the parent `SalesforceObject` if not specified.
Field	N/A	Field	Optional	Represents a field that should be set to a pre-determined value in Salesforce. Multiple `Field` elements can be provided. See Field for more info.
LookupField	N/A	LookupField	Optional	Represents a field where the value should be looked up in Salesforce. Multiple `LookupField` elements can be provided. See LookupField for more info.
RelatedObject	N/A	RelatedObject	Optional	Represents a child record that should be uploaded to Salesforce. Multiple `RelatedObject` elements can be provided. See RelatedObject for more info.

<?xml version="1.0"?>
<SalesforceObjects Type="Opportunity">
    <SalesforceObject>
        <RelatedObject Type="OpportunityLineItem" Key="Id" Operation="Upsert">
            <Field Name="OpportunityId" Value="{ParentId}" />
            <LookupField Name="UnitPrice" Select="UnitPrice" From="PricebookEntry">
                <WhereField Name="ProductCode" Value="IPHONE4" />
                <WhereField Name="Pricebook2.Name" Value="Standard" />
            </LookupField>
            <RelatedObject>
                <!-- Further child records can be specified like this -->
            </RelatedObject>
        </RelatedObject>
    </SalesforceObject>
</SalesforceObjects>