Apex Developer Guide

Apex Developer Guide
Release Notes
Getting Started with Apex
Writing Apex
Data Types and Variables
Control Flow Statements
Classes, Objects, and Interfaces
Working with Data in Apex
Working with sObjects
Data Manipulation Language
How DML Works
Adding and Retrieving Data With DML
DML Statements vs. Database Class Methods
DML Operations As Atomic Transactions
DML Operations
Inserting and Updating Records
Relating Records by Using an External ID
Creating Parent and Child Records in a Single Statement Using Foreign Keys
Upserting Records
Merging Records
Deleting Records
Restoring Deleted Records
Converting Leads
Exception Handling
More About DML
Locking Records
SOQL and SOSL Queries
SOQL For Loops
sObject Collections
Dynamic Apex
Apex Security and Sharing Model
Custom Settings
Document Your Apex Code
Running Apex
Debugging, Testing, and Deploying Apex
Apex Reference
Appendices
PDF

Note: This release is in preview. Features described here don’t become generally available until the latest general availability date that Salesforce announces for this release. Before then, and where features are noted as beta, pilot, or developer preview, we can’t guarantee general availability within any particular time frame or at all. Make your purchase decisions only on the basis of generally available products and features.

Relating Records by Using an External ID

Add related records by using a custom external ID field on the parent record. Associating records through the external ID field is an alternative to using the record ID. You can add a related record to another record only if a relationship (such as master-detail or lookup) has been defined for the objects involved.

Where possible, we changed noninclusive terms to align with our company value of Equality. We maintained certain terms to avoid any effect on customer implementations.

Important

This example relates a new opportunity to an existing account. The Account sObject has a custom field marked as External ID. An opportunity record is associated to the account record through the custom External ID field. The example assumes that:
  • The Account sObject has an external ID field of type text and named MyExtID
  • An account record exists where MyExtID__c = ‘SAP111111’
Before the new opportunity is inserted, the account record is added to this opportunity as an sObject through the Opportunity.Account relationship field. 
1Opportunity newOpportunity = new Opportunity(
2    Name='OpportunityWithAccountInsert',
3    StageName='Prospecting',
4    CloseDate=Date.today().addDays(7));
5
6// Create the parent record reference.
7// An account with external ID = 'SAP111111' already exists.
8// This sObject is used only for foreign key reference
9// and doesn't contain any other fields.
10Account accountReference = new Account(
11    MyExtID__c='SAP111111');                
12
13// Add the account sObject to the opportunity.
14newOpportunity.Account = accountReference;
15
16// Create the opportunity.
17Database.SaveResult results = Database.insert(newOpportunity);

The previous example performs an insert operation, but you can also relate sObjects through external ID fields when performing updates or upserts. If the parent record doesn’t exist, you can create it with a separate DML statement or by using the same DML statement as shown in Creating Parent and Child Records in a Single Statement Using Foreign Keys.