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 might also 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 the Salesforce online help.

Updateable Objects

Certain records cannot 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 cannot 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 cannot 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 (6 allowed).

Automatically Updated Fields

The API updates certain fields automatically, such as LastModifiedDate, LastModifiedById, and SystemModstamp. You cannot 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 cannot 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 will handle 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 big 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, then 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. 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

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 is not automatically subscribed to the record, unless the new owner has automatic subscriptions for records enabled in his or her Chatter feed settings. The previous owner is not 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.

Updating 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 objects types in one call.

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

Records for different object types are broken into multiple chunks by Salesforce. 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 once per chunk. Consider an sObjects input array containing the following set of records:

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

Salesforce splits the records into five chunks:

1. account1, account2
2. contact1, contact2, contact3
3. case1
4. account3, account4
5. 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.

Warning

You can't update records for multiple object types in one call if one of those types is related to a feature in the Setup area in Salesforce. The only exceptions are the following objects:

• Custom settings objects, which are similar to custom objects. For more information, see “Custom Settings Overview” in the Salesforce online help.
• GroupMember
• Group
• User if the following fields are not being updated:
  • UserRoleId
  • IsActive
  • ForecastEnabled
  • IsPortalEnabled
  • Username
  • ProfileId

update() and Foreign Keys

You can use external ID fields as a foreign key, which allows you to update a record and relate it to another existing record in a single step instead of querying the parent record ID first. To do this, set the foreign key to an instance of the parent sObject that has only the external ID field specified. This external ID should 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. Once 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

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