create

Use create to add one or more individual objects, such as an Account or Contact, to your organization's information. The create call is analogous to the INSERT statement in SQL.

Rules and Guidelines

Permissions

Your client application must be logged in with sufficient access rights to create individual objects within the specified 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 this object's parent object. Before you attempt to create a particular object, be sure to read its description in Chapter 5: sforce Objects.

Createable Fields

Certain objects cannot be created via the sforce API. To create an object via the create call, its object must be configured as createable (createable=True). To determine whether a given object can be created, your client application can invoke the describeSObject call on the object and inspect its createable property.

Automatically Maintained Fields

The sforce Web service generates unique values for ID fields automatically. For create, you cannot explicitly specify an ID value in the sObject. The SaveResult contains the ID of each object that was successfully created.

The sforce Web service populates certain fields automatically, such as CreatedDate, CreatedById, LastModifiedDate, LastModifiedById, and SystemModstamp. You cannot explicitly specify these values.

Required Fields

For required fields that do not have a preconfigured default value, you must supply a value. For more information, see Required Fields.

Default Values

For some objects, certain fields have a default value, such as OwnerID. If you do not specify a value for such fields, the sforce Web service populates these fields with the default value. For example, if you do not override the OwnerID, then the sforce Web service populates this field with the user ID associated with the user under which your client application is logged in.

For required fields that do not have a preconfigured default value, you must supply a value.

For all other fields in the object, if you do not explicitly specify a value, then its value is null.

Referential Integrity

Your client application must conform to the rules of referential integrity. For example, if you are creating an object that is the child of a parent object, you must supply the foreign key information that links the child to the parent. For example, when creating a CaseComment, you must supply the valid caseID for the parent Case, and that parent Case must exist in the database.

Valid Data 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 sforce Web service trims any leading and trailing whitespace. 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".

Assignment Rules

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

Maximum Number of Objects Created.

Your client application can add up to 200 individual objects in a single create call. If a create request exceeds 200 objects, then the entire operation fails.

Basic Steps for Creating Objects

Instantiate one or more individual objects within the object. For each object, you populate its fields with the data that you want to add.

Construct an sObject[] array and populate that array with the objects that you want to create. All objects must be of the same object.

Call create, passing in the sObject[] array.

Process the results in the SaveResult[] object to verify whether the objects have been successfully created.

Sample Code-Java

public void createAccountSample() { 
 
   // Create two account objects 
   Account account1 = new Account(); 
   Account account2 = new Account(); 
 
   // Set some fields on the account object 
   // Name field (required) not being set on account1,
   // so this record should fail during create. 
 
   account1.setAccountNumber("002DF99ELK9"); 
   account1.setBillingCity("Wichita"); 
   account1.setBillingCountry("US"); 
   account1.setBillingState("KA"); 
   account1.setBillingStreet("4322 Haystack Boulevard"); 
   account1.setBillingPostalCode("87901"); 
 
   // Set some fields on the account2 object 
   account2.setName("Golden Straw"); 
   account2.setAccountNumber("003DF99ELK9"); 
   account2.setBillingCity("Oaklanc"); 
   account2.setBillingCountry("US"); 
   account2.setBillingState("CA"); 
   account2.setBillingStreet("666 Raiders Boulevard"); 
   account2.setBillingPostalCode("97502"); 
 
   // Create an array of SObjects to hold the accounts 
   SObject[] sObjects = new SObject[2]; 
 
   // Add the accounts to the SObject array 
   sObjects[0] = account1; 
   sObjects[1] = account2; 
 
   // Invoke the create call 
   SaveResult[] saveResults = binding.create(sObjects); 
 
   // Handle the results 
   for (int i=0;i<saveResults.length;i++) { 
      // Determine whether create succeeded or had errors 
      if (saveResults[i].isSuccess()) { 
         // No errors, so we will retrieve the id created for this index 
         System.out.println(saveResults[i].getId().getValue()); 
      } 
      else { 
         // Handle the errors 
         ... 
      } 
   } 
}

Sample Code-C#

private void createAccount() 
{ 
   // Create an account object to send to the service 
   Account account = new Account(); 
 
   // Set several properties 
   account.Name = "Koka Kola"; 
   account.Website = "www.kokakola.com"; 
 
   // Add the account to an array of SObjects 
   sObject[] records = new sObject[] {account}; 
 
   // Invoke the create call, passing in the account properties 
   // and saving the results in a SaveResult object 
   SaveResult[] saveResults = binding.create(records); 
 
   // Access the new ID 
   String newID = saveResults[0].id; 
}