update()

Syntax

SaveResult[] = connection.update(sObject[] sObjects);

Usage

Use this call to update one or more existing records, such as accounts or contacts, in your organization's data. The update() call is analogous to the UPDATE statement in SQL.

Permissions

Your client application must be logged in with sufficient access rights to update() records objects for the specified object, as well as individual fields inside that object. For more information, see Factors that Affect Data Access.

Special Handling

Certain objects—and certain fields within those objects—require special handling or permissions. For example, you need permissions to access an object's parent object. Before you attempt to update a record for a particular object, be sure to read its description in the Standard Objects and in Salesforce Help.

Updateable Objects

Certain records can’t be updated via the API. To update a record via the update() call, its object must be configured as updateable (updateable is true). To determine whether an object can be updated, your client application can invoke the describeSObjects() call on the object and inspect its updateable property.

Required Fields

When updating required fields, you must supply a value—you can’t set the value to null. For more information, see Required Fields.

ID Fields

Fields whose names contain “Id” are either that object's primary key (see ID Field Type ) or a foreign key (see Reference Field Type). Client applications can’t update primary keys, but they can update foreign keys. For example, a client application can update the OwnerId of an Account, because OwnerID is a foreign key that refers to the user who owns the account record. Use describeSObjects() to confirm whether the field can be updated.

Maximum number of duplicate updates in one batch (12 allowed).

Automatically Updated Fields

The API updates certain fields automatically, such as LastModifiedDate, LastModifiedById, and SystemModstamp. You can’t explicitly specify these values in your update() call.

Resetting Values to null

To reset a field value to null, you add the field name to the fieldsToNull array in the sObject. You can’t set required fields (nillable is false) to null.

Valid Field Values

You must supply values that are valid for the field's data type, such as integers (not alphabetic characters) for integer fields. In your client application, follow the data formatting rules specified for your programming language and development tool (your development tool handles the appropriate mapping of data types in SOAP messages).

String Values

When storing values in string fields, the API trims any leading and trailing white space. For example, if the value of a name field is entered as " ABC Company ", then the value is stored in the database as "ABC Company".

Starting with API version 15.0, if you specify a value for a field that contains a string, and the value is too large for the field, the call fails, and an error is returned. In previous versions of the API the value was truncated and the call succeeded. If you wish to keep the old behavior with versions 15.0 and later, use the AllowFieldTruncationHeader SOAP header.

Assignment Rules

When updating Case or Lead objects, your client application can set AssignmentRuleHeader options to have the case or lead automatically assigned to one or more users based on assignment rules configured in the Salesforce user interface. For more information, see Case or Lead.

Maximum Number of Objects Updated

Your client application can change up to 200 records in a single update() call. If an update request exceeds 200 records, the entire operation fails.

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. Lets a call roll back all changes unless all records are processed successfully.

Automatic Subscriptions for Chatter Feeds

To subscribe to records they create, users must enable the Automatically follow records that I create option in their personal settings. If users have automatic subscriptions enabled, they automatically follow the records they create and see changes to those records in their Chatter feed on the Home tab.

When you update the owner of a record, the new owner isn’t automatically subscribed to the record, unless the new owner has automatic subscriptions for records enabled in their Chatter feed settings. The previous owner isn’t automatically unsubscribed. If the new owner has automatic subscriptions for records enabled, the new and previous owners both see any changes to the record in their news feed.

A user can subscribe to a record or to another user. Changes to the record and updates from the users are displayed in the Chatter feed on the user's home page, which is a useful way to stay up to date with other users and with changes made to records in Salesforce. Feeds are available in API version 18.0 and later.

Update Records for Different Object Types

You can update records for multiple object types, including custom objects, in one call with API version 20.0 and later. For example, you could update a contact and an account in one call. You can update records for up to 10 object types in one call.

Records are saved in the same order that they’re entered in the sObjects input array.

Salesforce breaks records for different object types into multiple chunks. A chunk is a subset of the sObjects input array and each chunk contains records of one object type. Data is committed on a chunk-by-chunk basis. Any Apex triggers related to the records in a chunk are invoked one time per chunk. Consider an sObjects input array containing this set of records.

account1, account2, contact1, contact2, contact3, case1, account3, account4, contact4

Salesforce splits the records into five chunks.

• account1, account2
• contact1, contact2, contact3
• case1
• account3, account4
• contact4

Each call can process up to 10 chunks. If the sObjects array contains more than 10 chunks, you must process the records in more than one call.

update() and Foreign Keys

You can use external ID fields as a foreign key, which lets you update a record and relate it to another existing record in a single step instead of querying the parent record ID first. To use an external ID as a foreign key, set the foreign key to an instance of the parent sObject that has only the external ID field specified. This external ID must match the external ID value on the parent record.

The following Java and C# examples show you how to update an opportunity and relate it to an existing account using a custom external ID field named MyExtId__c. Each example has a method that accepts the ID of the opportunity to update. It creates an opportunity sObject and sets its ID field so that the object points to an existing opportunity to be updated, sets a new value for the stage name field, and then sets the external ID field to the account object. It then updates the opportunity. After the opportunity is updated, the account becomes its parent and the state name is updated.

Java Example

public void updateForeignKeySample(String oppId) {
   try {
      Opportunity updateOpportunity = new Opportunity();
      // Point to an existing opportunity to update
      updateOpportunity.setId(oppId);
      updateOpportunity.setStageName("Qualification");

      Account parentAccountRef = new Account();
      parentAccountRef.setMyExtId__c("SAP1111111");
      updateOpportunity.setAccount(parentAccountRef);

      SaveResult[] results = connection
            .update(new SObject[] { updateOpportunity });
   } catch (ConnectionException ce) {
      ce.printStackTrace();
   }
}

C# Example

public void updateForeignKeySample(String oppId)
{
   try
   {
      Opportunity updateOpportunity = new Opportunity();
      // Point to an existing opportunity to update
      updateOpportunity.Id = oppId;
      updateOpportunity.StageName = "Prospecting";

      Account parentAccountRef = new Account();
      parentAccountRef.MyExtId__c = "SAP1111111";
      updateOpportunity.Account = parentAccountRef;

      SaveResult[] results = binding.update(
         new sObject[] { updateOpportunity });
   }
   catch (SoapException e)
   {
      Console.WriteLine("An unexpected error has occurred: " +
                                 e.Message + "\n" + e.StackTrace);
   }
}

Basic Steps for Updating Records

Use this process to update records.

1. Determine the ID of each record that you want to update(). For example, you can call query() to retrieve a set of records (with their IDs), based on specific criteria, that you would want to update. If you know the ID of the record that you want to update, you can call retrieve() instead. For information on IDs, see ID Field Type.
2. Create an sObject for each record, and populate its fields with the data that you want to update.
3. Construct an sObject[] array and populate that array with the records that you want to update.
4. Call update(), passing in the sObject[] array.
5. Process the results in the SaveResult[] object to verify whether the records have been successfully updated.

Sample Code—Java

This sample accepts the IDs of the accounts to update. It creates two account sObjects, sets each with one of the passed IDs so that the sObject points to an existing account, and sets other fields. It then makes the update() call and verifies the results.

public void updateRecords(String[] ids) {
   Account[] updates = new Account[2];

   Account account1 = new Account();
   account1.setId(ids[0]);
   account1.setShippingPostalCode("89044");
   updates[0] = account1;

   Account account2 = new Account();
   account2.setId(ids[1]);
   account2.setNumberOfEmployees(1000);
   updates[1] = account2;

   // Invoke the update call and save the results
   try {
      SaveResult[] saveResults = connection.update(updates);
      for (SaveResult saveResult : saveResults) {
         if (saveResult.isSuccess()) {
            System.out.println("Successfully updated Account ID: "
                  + saveResult.getId());
         } else {
            // Handle the errors.
            // We just print the first error out for sample purposes.
            Error[] errors = saveResult.getErrors();
            if (errors.length > 0) {
               System.out.println("Error: could not update " + "Account ID "
                     + saveResult.getId() + ".");
               System.out.println("\tThe error reported was: ("
                     + errors[0].getStatusCode() + ") "
                     + errors[0].getMessage() + ".");
            }
         }
      }
   } catch (ConnectionException ce) {
      ce.printStackTrace();
   }
}

Sample Code—C#

This sample accepts the IDs of the accounts to update. It creates two account sObjects, sets each with one of the passed IDs so that the sObject points to an existing account, and sets other fields. It then makes the update() call and verifies the results.

public void updateRecords(String[] ids)
{
   Account[] updates = new Account[2];

   Account account1 = new Account();
   account1.Id = ids[0];
   account1.ShippingPostalCode = "89044";
   updates[0] = account1;

   Account account2 = new Account();
   account2.Id = ids[1];
   account2.NumberOfEmployees = 1000;
   updates[1] = account2;

   // Invoke the update call and save the results
   try
   {
      SaveResult[] saveResults = binding.update(updates);
      foreach (SaveResult saveResult in saveResults)
      {
         if (saveResult.success)
         {
            Console.WriteLine("Successfully updated Account ID: " +
                  saveResult.id);
         }
         else
         {
            // Handle the errors.
            // We just print the first error out for sample purposes.
            Error[] errors = saveResult.errors;
            if (errors.Length > 0)
            {
               Console.WriteLine("Error: could not update " +
                     "Account ID " + saveResult.id + "."
               );
               Console.WriteLine("\tThe error reported was: (" +
                     errors[0].statusCode + ") " +
                     errors[0].message + "."
               );
            }
         }
      }
   }
   catch (SoapException e)
   {
      Console.WriteLine("An unexpected error has occurred: " +
                                 e.Message + "\n" + e.StackTrace);
   }
}

Arguments

Response

SaveResult[]

Faults

InvalidSObjectFault

UnexpectedErrorFault