Bulk API Developer's Guide
jNewer Version Available
Relationship Fields in a Header Row
Many objects in Salesforce are related to other objects. For example, Account is a parent of Contact. You can add a reference to a related object in a CSV file by representing the relationship in a column header. When you're processing records in the Bulk API, you use RelationshipName.IndexedFieldName syntax in a CSV column header to describe the relationship between an object and its parent, where RelationshipName is the relationship name of the field and IndexedFieldName is the indexed field name that uniquely identifies the parent record. Use the describeSObjects() call in the SOAP-based SOAP API to get the relationshipName property value for a field.
Some objects also have relationships to themselves. For example, the Reports To field for a contact is a reference to another contact. If you're inserting a contact, you could use a ReportsTo.Email column header to indicate that you're using a contact's Email field to uniquely identify the Reports To field for a contact. The ReportsTo portion of the column header is the relationshipName property value for the Reports To field. The following CSV file uses a relationship:
1FirstName,LastName,ReportsTo.Email
2Tom,Jones,buyer@salesforcesample.comNote the following when referencing relationships in CSV header rows:
- 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.
- You can only use indexed fields on the parent object. A custom field is indexed if its External ID field is selected. A standard field is indexed if its idLookup property is set to true. See the Field Properties column in the field table for each standard object.
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 representing the relationship in a column header.
If the child object has a custom field with an API Name of Mother_Of_Child__c that points to a parent custom object and the parent object has a field with an API Name of External_ID__c, use the column header Mother_Of_Child__r.External_ID__c to indicate that you're using the parent object's External ID field to uniquely identify the Mother Of Child field. To use a relationship name in a column header, 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 CSV file uses a relationship:
1Name,Mother_Of_Child__r.External_ID__c
2CustomObject1,123456Relationships 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 column header has an extra element to define the type of the parent object. The syntax is ObjectType:RelationshipName.IndexedFieldName. The following sample includes 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.
1Subject,Priority,Status,Lead:Who.Email,Owner.Id
2Test Bulk API polymorphic reference field,Normal,Not Started,lead@salesforcesample.com,005D0000001AXYz