Bulk API 2.0 and Bulk API Developer Guide
jNewer Version Available
Relationship Fields in Records
To add a reference to a related object for a field in a JSON or XML record, use the following syntax to represent the relationship. The RelationshipName is the relationship name of the field, and IndexedFieldName is the indexed field name that identifies the parent record.
JSON:
1"RelationshipName" : { "IndexedFieldName" : "rwilliams@salesforcesample.com" }XML:
1<RelationshipName>
2 <sObject>
3 <IndexedFieldName>rwilliams@salesforcesample.com</IndexedFieldName>
4 </sObject>
5</RelationshipName>Use the describeSObjects() call in the API to get the relationshipName property value for a field. Use an indexed field to uniquely identify the parent record for the relationship. A standard field is indexed if its idLookup property is set to true.
These samples include a contact record that includes the ReportsTo field, which is a reference to another contact. ReportsTo is the relationshipName property value for the ReportsTo field. In this case, the parent object for the ReportsTo field is also a contact, so we use the Email field to identify the parent record. The idLookup property value for the Email field is true. To see if there is a idLookup property for a field, go to the Field Properties column in the field table for each standard object.
JSON:
1[{
2 "FirstName" : "Ray",
3 "LastName" : "Riordan",
4 "ReportsTo" : { "Email" : "rwilliams@salesforcesample.com" }
5}]XML:
1<?xml version="1.0" encoding="UTF-8"?>
2<sObjects xmlns="http://www.force.com/2009/06/asyncapi/dataload">
3 <sObject>
4 <FirstName>Ray</FirstName>
5 <LastName>Riordan</LastName>
6 <ReportsTo>
7 <sObject>
8 <Email>rwilliams@salesforcesample.com</Email>
9 </sObject>
10 </ReportsTo>
11 </sObject>
12</sObjects>When using relationships in JSON or XML records:
- You can use a child-to-parent relationship, but you can't use a parent-to-child relationship.
- You can use a child-to-parent relationship, but you can't extend it to use a child-to-parent-grandparent relationship.
Relationship Fields for Custom Objects
Custom objects use custom fields to track relationships between objects. Use the relationship name, which ends in __r (underscore-underscore-r), to represent a relationship between two custom objects. You can add a reference to a related object by using an indexed field. A custom field is indexed if its External ID field is selected.
For example, let’s say a child object has a custom field with an API Name of Mother_Of_Child__c that points to a parent custom object. Let’s assume that the parent object has a field with an API Name of External_ID__c. You can use the Mother_Of_Child__r relationshipName property to indicate that you’re referencing a relationship to the parent object. Use the parent object’s External ID field as a unique identifier for the Mother Of Child field. To use a relationship name, replace the __c in the child object’s custom field with __r. For more information about relationships, see Understanding Relationship Names in the Salesforce SOQL and SOSL Reference Guide at www.salesforce.com/us/developer/docs/soql_sosl/index.htm.
The following JSON and XML files show usage of the relationship.
JSON:
1[{
2 "Name" : "CustomObject1",
3 "Mother_Of_Child__r" : { "External_ID__c" : "123456" }
4}]XML:
1<?xml version="1.0" encoding="UTF-8"?>
2<sObjects xmlns="http://www.force.com/2009/06/asyncapi/dataload">
3 <sObject>
4 <Name>CustomObject1</Name>
5 <Mother_Of_Child__r>
6 <sObject>
7 <External_ID__c>123456</External_ID__c>
8 </sObject>
9 </Mother_Of_Child__r>
10 </sObject>
11</sObjects>Relationships for Polymorphic Fields
A polymorphic field can refer to more than one type of object as a parent. For example, either a contact or a lead can be the parent of a task. In other words, the WhoId field of a task can contain the ID of either a contact or a lead. Since a polymorphic field is more flexible, the syntax for the relationship field has an extra element to define the type of the parent object. The following JSON and XML samples show the syntax, where RelationshipName is the relationship name of the field, ObjectTypeName is the object type of the parent record, and IndexedFieldName is the indexed field name that uniquely identifies the parent record.
JSON:
1"RelationshipName" : {
2 "attributes" : {
3 "type" : "ObjectTypeName" },
4 "IndexedFieldName" : "rwilliams@salesforcesample.com"
5}XML:
1<RelationshipName>
2 <sObject>
3 <type>ObjectTypeName</type>
4 <IndexedFieldName>rwilliams@salesforcesample.com</IndexedFieldName>
5 </sObject>
6</RelationshipName>These samples include two reference fields.
- The WhoId field is polymorphic and has a relationshipName of Who. It refers to a lead and the indexed Email field uniquely identifies the parent record.
- The OwnerId field is not polymorphic and has a relationshipName of Owner. It refers to a user and the indexed Id field uniquely identifies the parent record.
JSON:
1[{
2 "Subject" : "Test Bulk API polymorphic reference field",
3 "Priority" : "Normal",
4 "Status" : "Not Started",
5 "Who" : {
6 "attributes" : {
7 "type" : "Lead" },
8 "Email" : "lead@salesforcesample.com" },
9 "Owner" : { "Id" : "005D0000001AXYz" }
10}]XML:
1<?xml version="1.0" encoding="UTF-8"?>
2<sObjects xmlns="http://www.force.com/2009/06/asyncapi/dataload">
3 <sObject>
4 <Subject>Test Bulk API polymorphic reference field</Subject>
5 <Priority>Normal</Priority>
6 <Status>Not Started</Status>
7 <Who>
8 <sObject>
9 <type>Lead</type>
10 <Email>lead@salesforcesample.com</Email>
11 </sObject>
12 </Who>
13 <Owner>
14 <sObject>
15 <Id>005D0000001AXYz</Id>
16 </sObject>
17 </Owner>
18 </sObject>
19</sObjects>