At the highest level, the Enterprise API consists of core services that allow query and modification of Force.com data, plus a set of types reflecting the standard and custom objects defined in your Force.com organization. Using these core services and types is a fairly straightforward exercise after your code has established a session with Force.com.
This section divides the Enterprise API into four functional groups, described here:
1. Retrieving records—Retrieve records using SOQL or SOSL queries, by unique identifier, or based on their modification or deletion time stamp.
2. Writing records—Learn how to create and update records using the Enterprise API.
3. Deleting and undeleting records—By deleting records, you send them to the recycling bin, where they can later be undeleted if necessary.
4. Modifications in bulk—Modifications can be performed on up to 200 records at a time to conserve API calls and improve performance.
The most common way to retrieve records is via SOQL. This is accomplished with the query
service. A SOQL statement is passed as input, and a QueryResult
object is returned. This object contains an array of records returned by the query.
The number of records returned by the query
service is a function of the batch size. The default batch size in Java using WSC is 2,000 records, 500 for Axis and other Web service clients. If a query result contains more records than the batch size, use the queryMore
service to retrieve additional batches of records.
The code in Listing 10.17 demonstrates the query
and queryMore
services in Java to build a list of Project records.
List<Project__c> projects = new ArrayList<Project__c>();
QueryResult qr = connection.query("SELECT Id, Name FROM Project__c");
boolean done = false;
if (qr.getSize() > 0) {
while (!done) {
SObject[] records = qr.getRecords();
if (records != null) {
for (SObject record : records) {
projects.add((Project__c)record);
}
if (qr.isDone()) {
done = true;
} else {
qr = connection.queryMore(qr.getQueryLocator());
}
}
}
}
You can set a custom batch size (up to 2,000 records) by providing a QueryOptions
header. This is demonstrated in Java in Listing 10.18.
connection.setQueryOptions(2000);
There’s no guarantee Force.com will return the requested number of records in a batch. For example, if a SOQL statement selects two or more custom fields of type long text, the batch size will never be more than 200 records. Queries on binary data always return a single record at a time.
A few other approaches are available for retrieving records, described next:
Using SOSL—The search
service executes a SOSL statement and returns a Search Result
object, which contains an array of SearchRecord
objects. Each SearchRecord
contains an SObject instance representing a matching record. Because SOSL can return many object types, each SearchRecord
object can contain a different type of SObject.
By unique identifier—If you know the unique identifier of an object, you can retrieve it by using the retrieve
service. Its inputs are a string containing a comma-separated list of field names to retrieve, the type of object as a string, and an array of up to 2,000 record unique identifiers. It returns an array of SObject instances.
By time stamp—The getUpdated
and getDeleted
services return the unique identifiers of records updated or deleted between a range of dates.
The basic services for writing records closely resemble their counterparts in Apex code. Services exist for creating, updating, upserting, deleting, and undeleting records. These services can accept one record at a time or up to 200 records in a single invocation.
To create one or more records, invoke the create
service, passing in an array of SObjects. Each SObject must contain at a minimum the values for the required fields defined on the object. The service returns an array of SaveResult
objects. Each SaveResult
indicates success or failure of an individual record. In the case of failure, the SaveResult
also contains an array of Error
objects indicating the error reason.
The code in Listing 10.19 demonstrates the create
service in Java. It creates a Contact record from the values of firstName
and lastName
.
Contact contact = new Contact();
contact.setFirstName(firstName);
contact.setLastName(lastName);
SaveResult[] result = connection.create(
new SObject[] { contact });
if (result != null && result.length == 1) {
if (result[0].isSuccess()) {
System.out.println("Created contact with Id: "
+ result[0].getId());
} else {
System.out.println("Failed to create contact: " +
result[0].getErrors()[0].getMessage());
}
}
To modify existing records, use the update
service. Its arguments and return value are identical to those of the create
method. The major difference is that the SObjects must contain a value for the Id
field. This value is the unique identifier of the record to be updated.
Use the upsert
service when you want to create records that don’t exist and update them if they do exist. To determine whether a record exists, the upsert
service examines a field containing unique identifiers. This field can be the internal Id
field or a custom field designated as an external identifier. The first argument to the upsert
service is the name of the unique identifier field, and the second is an array of SObjects. The service returns an array of UpsertResult
objects. Like the SaveResult
object, it contains a success or failure indicator and an array of errors upon failure.
Note
You must perform an additional step to set fields to null during an update or upsert. Each object instance has a special array field called fieldsToNull
. To set a field to null, add the name of the field to this list.
To delete records, call the delete
service and pass in an array of record unique identifiers to delete. Unlike the other DML operations, delete
accepts different types of objects in a single call. The service returns an array of DeleteResult
objects indicating the success or failure of each deletion, as well as any error messages.
The undelete
service restores deleted records from the Recycle Bin. Its input is a list of record unique identifiers, and it returns an array of UndeleteResult
objects for use in tracking the outcome of each undeletion.
Bulk modifications involve more than one record. You can create, update, upsert, delete, or undelete a maximum of 200 records in a single call. By default, Force.com allows partial failure, meaning some records can fail while others succeed. To override this behavior, add the AllOrNoneHeader
to the call and set it to true
. This causes Force.com to roll back all modifications made by the call unless all records are successfully processed.
The ability to process multiple object types in a single call is a powerful feature of bulk modifications. This is supported on create, update, delete, and undelete operations, but not upsert. For example, you can create a Resource and Skill in one round-trip to Force.com. This requires that the Skill record references its parent Resource using an external identifier rather than an Id because an Id for the record doesn’t exist yet.
There are several important limitations of bulk create and update calls that involve multiple object types:
Up to ten unique object types are allowed per call.
You can’t reference a new record of the same type in a single call. For example, if two Contact records were related to each other, you would need to create the parent first and then create the child and relate it to the parent in a separate call.
If there are related records in the call, parent records must be located ahead of child records in the request.
You cannot modify records of multiple object types if they participate in the Salesforce Setup menu. This limitation includes custom settings objects, GroupMember, Group, and User.
3.22.74.3