upsert()

Syntax

UpsertResult[] = connection.upsert(String externalIdFieldName, sObject[] sObjects);

Usage

Upsert is a merging of the words insert and update. This call is available for objects if the object has an external ID field or a field with the idLookup field property.

How Upsert Chooses to update() or create()

Upsert uses the external ID to determine whether it should create a new record or update an existing one:

• If the external ID is not matched, then a new record is created.
• If the external ID is matched once, then the existing record is updated.
• If the external ID is matched multiple times, then an error is reported.
• When batch updating multiple records where the external ID is the same for two or more records in your batch call, those records will be marked as errors in the UpsertResult file. The records will be neither created or updated.

Rollback on Error

The AllOrNoneHeader header allows you to roll back all changes unless all records are processed successfully. This header is available in API version 20.0 and later. The default behavior is to allow partial success of a call: records without errors are committed, while records with errors are marked as failed in the call results.

Automatic Subscriptions for Chatter Feeds

When you create a new record, the owner is automatically subscribed to the record, meaning they follow the record in Chatter and see changes to that record in their Chatter feed on the Home tab. When you update the owner of a record, the new owner is automatically subscribed to the record. The previous owner is not automatically unsubscribed. This means that the new and previous owners both see any changes to the record in their news feed. The subscription occurs unless the user has selected the Stop automatically following records checkbox in Your Name | Setup | My Chatter Settings | My Feeds.

A user can subscribe to a record so that changes to the record are displayed in the Chatter feed on the user's home page, which is a useful way to stay up-to-date with changes made to records in Salesforce. Feeds are available in API version 18.0 and later.

upsert() and Foreign Keys

You can use external ID fields as a foreign key, allowing you to access records in a single step instead of querying a record to get the ID first. To do this, specify the foreign key name and the external ID field value.

The following example upserts an Opportunity. The Opportunity references an Account. Rather than specify the account ID, which would require a separate query to obtain, we specify an external ID for the account, in this example the External_SAP1_ACCTID__c custom field.

public void upsertForeignKeySample()
{
  Opportunity upsertOpportunity = new Opportunity();
  upsertOpportunity.setStageName("Prospecting");
  //To indicate the reference, attach an Account object,
  //which has only the external ID field specified.
  Account upsertParentAccountRef = new Account();
  upsertParentAccountRef.setExternal_SAP1_ACCTID__c("SAP111111");
  upsertOpportunity.setAccount(upsertParentAccountRef);
  //Set the external ID for the Opportunity
  upsertOpportunity.set_SAP1_OPPID__c("SAP222222");
  UpsertResult[] upsertResults = binding.upsert("SAP1_OPPID__c",
            new SObject[] {upsertOpportunity});
  // check results and do more processing after the upsert call ...
}

upsert() and Polymorphic Foreign Keys

A polymorphic key is an ID that can refer to more than one type of object as a parent. For example, the OwnerId field on the Case object can reference either a User or a Group. Similarly, the WhoID field on the Task object can reference either a Contact or a Lead.

With the Enterprise WSDL, such polymorphic foreign key fields are defined as a Name sObject type, so it is not possible to pass in the correct sObject in an upsert() call. However, with the Partner WSDL all foreign key fields—including polymorphic ones—are of type sObject , which allows upsert() calls on such fields.

Sample Code—Java

The following sample is for an upsert specifying the Salesforce object ID.

public void upsertRecords() {
    SObject[] upserts = new Account[2];
    // This account is assumed to exist.
    // Could be from the results of a retrieve or query call.
    Account upsertAccount = new Account();
    upsertAccount.setWebsite("http://www.example.com");
    // A custom field External_ID__c is used
    // for "External ID" on Upsert
    upsertAccount.setExternal_ID__c("1111111111");
    upserts[0] = upsertAccount;
    // This account is new
    Account upsertAccount2 = new Account();
    upsertAccount2 = new Account();
    upsertAccount2.setName("My Company, Inc");
    upsertAccount2.setExternal_ID__c("2222222222");
    upserts[1] = upsertAccount2;
    try {
      // Invoke the upsert call and save the results.
      // Use External_Id custom field for matching records
      UpsertResult[] upsertResults =
          connection.upsert("External_ID__c", upserts);
      for (UpsertResult result : upsertResults) {
        if (result.isSuccess()) {
          System.out.println("\nUpsert succeeded.");
          System.out.println(
              (result.isCreated() ? "Insert" : "Update") + 
              " was performed."
          );         
          System.out.println("Account ID: " + result.getId());
        } else {
          System.out.println("The Upsert failed because: " + 
              result.getErrors()[0].getMessage());
        }
      }
    } catch (ConnectionException ce) {
      ce.printStackTrace();
    }
  }

Sample Code—C#

The following sample is for an upsert specifying the Salesforce object ID (not the foreign key).

private void upsertSample() 
{
   if (!loggedIn) {
      if (!login())return;
   }

   //First, create a contact using the upsert call.  The contact must have a custom 
    
   //field that is designated as an external id. In this case it's called ExternalId__c 
    
   sforce.Contact[] contact = new Contact[1];
   contact[0] = new sforce.Contact();
   contact[0].LastName = "External_Id";
   contact[0].FirstName = "Test"; 
   contact[0].ExternalId__c = "01010101";

   sforce.UpsertResult ur = binding.upsert("ExternalId__c", contact)[0];

   if (ur.success)
   { //Check out the created flag 
    
      Console.WriteLine("Value of created flag is: " + ur.created);
   }
   else
   {  //Report an error 
    
      Console.WriteLine("Error: \n" + ur.errors[0].message);
      return;
   }

   //Now, we can call the upsert again changing a value. 
    
   contact[0].FirstName = "Joe";
   contact[0].LastName = "Sampson";

   ur = binding.upsert("ExternalId__c", contact)[0];

   if (ur.success)
   {  //Check out the create flag, should be false now 
    
      Console.WriteLine("Value of created flag is: " + ur.created);
   } 
   else 
   {  //Report an error 
    
      Console.WriteLine("Error: \n" + ur.errors[0].message);
      return;
   }
}

Arguments

Response

UpsertResult[]

Faults

InvalidSObjectFault