Bulk API Developer Guide: Version 44.0, Winter '19
Bulk API Developer Guide: Version 44.0, Winter '19
Bulk API Developer Guide: Version 44.0, Winter '19
@salesforcedocs
Last updated: December 4, 2018
© Copyright 2000–2018 salesforce.com, inc. All rights reserved. Salesforce is a registered trademark of salesforce.com, inc.,
as are other names and marks. Other marks appearing herein may be trademarks of their respective owners.
CONTENTS
GLOSSARY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
Contents
INDEX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
CHAPTER 1 Introduction to Bulk API
The Bulk API provides a programmatic option to quickly load your org’s data into Salesforce. To use the API requires basic familiarity with
software development, web services, and the Salesforce user interface.
The functionality described is available only if your org has the Bulk APIfeature enabled. This feature is enabled by default for Performance,
Unlimited, Enterprise, and Developer Editions.
Important: Currently base64 fields are not supported in queries with the Bulk API.
1
Introduction to Bulk API
SEE ALSO:
Data Loader Guide
SOAP API Developer Guide
Metadata API Developer's Guide
Work with Jobs
Work with Batches
2
Introduction to Bulk API Use CORS to Access Salesforce Resources from Web
Browsers
Important: CORS does not support requests for unauthenticated resources, including OAuth endpoints. You must pass an OAuth
token with requests that require it.
3
CHAPTER 2 Quick Start
In this chapter ... Use this sample to create HTTP requests that insert new contact records using the REST-based Bulk API.
The instructions progress through logging in, submitting the records, checking status, and retrieving
• Set Up a Salesforce the results.
Developer Edition
Organization Note: Before you begin building an integration or other client application:
• Install cURL • Install your development platform according to its product documentation.
• Send HTTP Requests • Read through all the steps before beginning this quick start. You may also wish to review the
with cURL rest of this document to familiarize yourself with terms and concepts.
4
Quick Start Set Up a Salesforce Developer Edition Organization
Install cURL
The Bulk API uses HTTP GET and HTTP POST methods to send and receive CSV, XML, and JSON content, so it’s simple to build client
applications using the tool or the language of your choice. This quick start uses a command-line tool called cURL to simplify sending
and receiving HTTP requests and responses.
cURL is pre-installed on many Linux and Mac systems. Windows users can download a version at curl.haxx.se/. When using
HTTPS on Windows, ensure that your system meets the cURL requirements for SSL.
Escaping the Session ID or Using Single Quotes on Mac and Linux Systems
When running the cURL examples, you may get an error on Mac and Linux systems due to the presence of the exclamation mark
special character in the session ID argument. To avoid getting this error, do one of the following:
• Escape the exclamation mark (!) special character in the session ID by inserting a backslash before it (\!) when the session ID is
enclosed within double quotes. For example, the session ID string in this cURL command has the exclamation mark (!) escaped:
curl https://instance_name.salesforce.com/services/async/44.0/job
-H "X-SFDC-Session:
00D50000000IehZ\!AQcAQH0dMHZfz972Szmpkb58urFRkgeBGsxL_QJWwYMfAbUeeG7c1E6
LYUfiDUkWe6H34r1AAwOR8B8fLEz6n04NPGRrq0FM"
curl https://instance_name.salesforce.com/services/async/44.0/job
-H 'X-SFDC-Session: sessionID'
5
Quick Start Step 1: Log In Using the SOAP API
The part after the API version (Resource_address) varies depending on the job or batch being processed.
The easiest way to start using the Bulk API is to enable it for processing records in Data Loader using CSV files. If you use Data Loader,
you don't need to craft your own HTTP requests or write your own client application. For an example of writing a client application using
Java, see Sample Client Application Using Java on page 86.
SEE ALSO:
About URIs
Data Loader Guide
2. Replace your_username and your_password with your Salesforce user name and password.
6
Quick Start Step 2: Create a Job
The Soap/u/ portion of the URI specifies the partner WSDL. You can use Soap/c/ to specify the enterprise WSDL.
4. Salesforce returns an XML response that includes <sessionId> and <serverUrl> elements. Note the values of the
<sessionId> element and the first part of the host name (instance), such as yourInstance-api, from the <serverUrl>
element. Use these values in subsequent requests to the Bulk API.
SEE ALSO:
Set a Session Header
SOAP API Developer Guide
Warning: The operation value must be all lower case. For example, you get an error if you use INSERT instead of insert.
Note: When running cURL examples, you may get an error on Mac and Linux systems due to the presence of the exclamation
mark special character in the session ID argument. To avoid getting this error, either escape the exclamation mark by inserting
a backslash before it (\!) or enclose the session ID within single quotes.
Salesforce returns an XML response with data such as the following:
<?xml version="1.0" encoding="UTF-8"?>
<jobInfo
xmlns="http://www.force.com/2009/06/asyncapi/dataload">
<id>750x0000000005LAAQ</id>
<operation>insert</operation>
<object>Contact</object>
<createdById>005x0000000wPWdAAM</createdById>
<createdDate>2009-09-01T16:42:46.000Z</createdDate>
7
Quick Start Step 3: Add a Batch to the Job
<systemModstamp>2009-09-01T16:42:46.000Z</systemModstamp>
<state>Open</state>
<concurrencyMode>Parallel</concurrencyMode>
<contentType>CSV</contentType>
<numberBatchesQueued>0</numberBatchesQueued>
<numberBatchesInProgress>0</numberBatchesInProgress>
<numberBatchesCompleted>0</numberBatchesCompleted>
<numberBatchesFailed>0</numberBatchesFailed>
<numberBatchesTotal>0</numberBatchesTotal>
<numberRecordsProcessed>0</numberRecordsProcessed>
<numberRetries>0</numberRetries>
<apiVersion>44.0</apiVersion>
<numberRecordsFailed>0</numberRecordsFailed>
<totalProcessingTime>0</totalProcessingTime>
<apiActiveProcessingTime>0</apiActiveProcessingTime>
<apexProcessingTime>0</apexProcessingTime>
</jobInfo>
3. Note the value of the job ID returned in the <id> element. Use this ID in subsequent operations.
SEE ALSO:
Create a Job
The value for the Description field in the last row spans multiple lines, so it’s wrapped in double quotes.
8
Quick Start Step 4: Close the Job
Salesforce does not parse the CSV content or otherwise validate the batch until later. The response only acknowledges that the batch
was received.
3. Note the value of the batch ID returned in the <id> element. You can use this batch ID later to check the status of the batch.
SEE ALSO:
Prepare CSV Files
Add a Batch to a Job
Bulk API Limits
SEE ALSO:
Close a Job
9
Quick Start Step 5: Check Batch Status
If Salesforce can’t read the batch content or if the batch contains errors, such as invalid field names in the CSV header row, the batch
state is Failed. When the batch state is Completed, all records in the batch have been processed. However, individual records
could have failed. You need to retrieve the batch result to see the status of individual records.
You don’t have to check the status of each batch individually. You can check the status for all batches that are part of the job by running
the following cURL command:
curl https://instance.salesforce.com/services/async/44.0/job/jobId/batch -H
"X-SFDC-Session: sessionId"
SEE ALSO:
Get Information for a Batch
Get Information for All Batches in a Job
Interpret Batch State
10
Quick Start Step 6: Retrieve Batch Results
The response body is a CSV file with a row for each row in the batch request. If a record was created, the ID is contained in the row. If a
record was updated, the value in the Created column is false. If a record failed, the Error column contains an error message.
SEE ALSO:
Get Batch Results
Handle Failed Records in Batches
11
CHAPTER 3 Plan Bulk Data Loads
In this chapter ... In most circumstances, the Bulk API is significantly faster than the SOAP-based API for loading large
numbers of records. However, performance depends on the type of data that you're loading as well as
• General Guidelines any workflow rules and triggers associated with the objects in your batches. It's useful to understand
for Data Loads the factors that determine optimal loading time.
• Use Compression for
Responses
12
Plan Bulk Data Loads General Guidelines for Data Loads
Note: Because your data model is unique to your organization, Salesforce can't predict exactly when you might see lock
contention problems.
Minimize Number of Fields
Processing time is faster if there are fewer fields loaded for each record. Foreign key, lookup relationship, and roll-up summary fields
are more likely to increase processing time. It's not always possible to reduce the number of fields in your records, but, if it is possible,
loading times will improve.
Minimize Number of Workflow Actions
Workflow actions increase processing time.
Minimize Number of Triggers
You can use parallel mode with objects that have associated triggers if the triggers don't cause side-effects that interfere with other
parallel transactions. However, Salesforce doesn't recommend loading large batches for objects with complex triggers. Instead, you
should rewrite the trigger logic as a batch Apex job that is executed after all the data has loaded.
13
Plan Bulk Data Loads Use Compression for Responses
Note: For Bulk queries, the batch size is not applied to either the query result set, or the retrieved data size. If your bulk query
is taking too long to process, you will need to filter your query statement to return less data.
Minimize Number of Batches in the Asynchronous Queue
Salesforce uses a queue-based framework to handle asynchronous processes from such sources as future and batch Apex, as well
as Bulk API batches. This queue is used to balance request workload across organizations. If more than 2,000 unprocessed requests
from a single organization are in the queue, any additional requests from the same organization will be delayed while the queue
handles requests from other organizations. Minimize the number of batches submitted at one time to ensure that your batches are
not delayed in the queue.
Bulk API follows the HTTP 1.1 standards for response compression. Most clients automatically support compressed responses. Visit
https://developer.salesforce.com/page/Tools for more information on particular clients.
14
CHAPTER 4 Prepare Data Files
In this chapter ... The Bulk API processes records in comma-separated values (CSV) files, XML files, or JSON files.
• Find Field Names Note: For best performance, Salesforce recommends the following order of preference for data
• Valid Date Format in files: CSV, JSON, XML.
Records For information about loading records containing binary attachments, see Load Binary Attachments on
• Prepare CSV Files page 25.
• Prepare XML and For information about loading data from third-party sources, see Map Data Fields on page 100.
JSON Files
SEE ALSO:
Data Loader Guide
15
Prepare Data Files Find Field Names
SEE ALSO:
Salesforce Help: Find Object Management Settings
16
Prepare Data Files Prepare CSV Files
Tip: To import data from CSV files that don’t meet these rules, map the data fields in the CSV file to Salesforce data fields. See Map
Data Fields on page 100.
SEE ALSO:
Data Loader Guide
FirstName,LastName,ReportsTo.Email
Tom,Jones,buyer@salesforcesample.com
17
Prepare Data Files Valid CSV Record Rows
Warning: The ObjectType: portion of a field column header is only required for a polymorphic field. You get an error if you
omit this syntax for a polymorphic field. You also get an error if you include this syntax for a field that is not polymorphic.
18
Prepare Data Files Sample CSV File
• Fields with a double data type can include fractional values. Values can be stored in scientific notation if the number is large
enough (or, for negative numbers, small enough), as indicated by the W3C XML Schema Part 2: Datatypes Second Edition specification.
The Description field for the last record includes a line break, which is why the field value is enclosed in double quotes.
SEE ALSO:
Sample XML File
Sample JSON File
Data Loader Guide
19
Prepare Data Files Relationship Fields in Records
To add a reference to a related object for a field in a JSON or XML record, use the following syntax to represent the relationship. The
RelationshipName is the relationship name of the field, and IndexedFieldName is the indexed field name that identifies
the parent record.
JSON:
XML:
<RelationshipName>
<sObject>
<IndexedFieldName>rwilliams@salesforcesample.com</IndexedFieldName>
</sObject>
</RelationshipName>
Use the describeSObjects() call in the SOAP-based SOAP API to get the relationshipName property value for a field.
Use an indexed field to uniquely identify the parent record for the relationship. A standard field is indexed if its idLookup property
is set to true.
The following samples include a contact record that includes the Reports To field, which is a reference to another contact.
ReportsTo is the relationshipName property value for the Reports To field. In this case, the parent object for the
Reports To field is also a contact, so we use the Email field to identify the parent record. The idLookup property value for
the Email field is true. To see if there is a idLookup property for a field, see the Field Properties column in the field table for each
standard object.
JSON:
[{
"FirstName" : "Ray",
"LastName" : "Riordan",
"ReportsTo" : { "Email" : "rwilliams@salesforcesample.com" }
}]
XML:
<?xml version="1.0" encoding="UTF-8"?>
<sObjects xmlns="http://www.force.com/2009/06/asyncapi/dataload">
<sObject>
<FirstName>Ray</FirstName>
<LastName>Riordan</LastName>
<ReportsTo>
<sObject>
<Email>rwilliams@salesforcesample.com</Email>
</sObject>
</ReportsTo>
</sObject>
</sObjects>
20
Prepare Data Files Relationship Fields in Records
XML:
<?xml version="1.0" encoding="UTF-8"?>
<sObjects xmlns="http://www.force.com/2009/06/asyncapi/dataload">
<sObject>
<Name>CustomObject1</Name>
<Mother_Of_Child__r>
<sObject>
<External_ID__c>123456</External_ID__c>
</sObject>
</Mother_Of_Child__r>
</sObject>
</sObjects>
"RelationshipName" : {
"attributes" : {
"type" : "ObjectTypeName" },
"IndexedFieldName" : "rwilliams@salesforcesample.com"
}
21
Prepare Data Files Relationship Fields in Records
XML:
<RelationshipName>
<sObject>
<type>ObjectTypeName</type>
<IndexedFieldName>rwilliams@salesforcesample.com</IndexedFieldName>
</sObject>
</RelationshipName>
XML:
<?xml version="1.0" encoding="UTF-8"?>
<sObjects xmlns="http://www.force.com/2009/06/asyncapi/dataload">
<sObject>
<Subject>Test Bulk API polymorphic reference field</Subject>
<Priority>Normal</Priority>
<Status>Not Started</Status>
<Who>
<sObject>
<type>Lead</type>
<Email>lead@salesforcesample.com</Email>
</sObject>
</Who>
<Owner>
<sObject>
<Id>005D0000001AXYz</Id>
</sObject>
</Owner>
</sObject>
</sObjects>
Warning: The type element is required only for a polymorphic field. If you omit this element for a polymorphic field or include
it for a non-polymorphic field, you get an error.
22
Prepare Data Files Valid XML and JSON Records
Each batch in a JSON file uses the following format with each JSON object representing a record.
[
{
"field_name" : "field_value"
...
}
{
"field_name" : "field_value"
...
}
]
Note: You must include the type field for a polymorphic field and exclude it for non-polymorphic fields in any batch. The batch
fails if you do otherwise. A polymorphic field can refer to more than one type of object as a parent. For example, either a contact
or a lead can be the parent of a task. In other words, the WhoId field of a task can contain the ID of either a contact or a lead.
When generating records in XML or JSON files:
• Fields that aren’t defined in the file for a record are ignored when you update records. To set a field value to null in XML, set the
xsi:nil value for the field to true. For example, <description xsi:nil="true"/> sets the description field to
null. Setting xsi:nil to false has no effect. If you define a field value and set xsi:nil to false, the value still gets
assigned. To specify a null value in JSON, set the field value to null. For example, "description" : null.
• Fields with a double data type can include fractional values. Values can be stored in scientific notation if the number is large
enough (or, for negative numbers, small enough), as indicated by the W3C XML Schema Part 2: Datatypes Second Edition specification.
23
Prepare Data Files Sample JSON File
SEE ALSO:
Sample CSV File
Sample JSON File
SEE ALSO:
Sample CSV File
Sample XML File
24
CHAPTER 5 Load Binary Attachments
In this chapter ... The Bulk API can load binary attachments, which can be Attachment objects or Salesforce CRM Content.
• Create a request.txt
File
• Create a Zip Batch
File with Binary
Attachments
• Create a Job for
Batches with Binary
Attachments
• Create a Batch with
Binary Attachments
25
Load Binary Attachments Create a request.txt File
Note: The batch data file is named request.txt whether you’re working with CSV, XML, or JSON data.
For the Attachment object, the notation for the following fields is particularly important:
• The Name field is the file name of the binary attachment. The easiest way to get a unique name for each attachment in your batch
is to use the relative path from the base directory to the binary attachment. For example, attachment1.gif or
subdir/attachment2.doc.
• The Body is the relative path to the binary attachment, preceded with a # symbol. For example, #attachment1.gif or
#subdir/attachment2.doc.
• The ParentId field identifies the parent record, such as an account or a case, for the attachment.
The batch file can also include other optional Attachment fields, such as Description. For more information, see Attachment.
Name,ParentId,Body
attachment1.gif,Account Id,#attachment1.gif
subdir/attachment2.doc,Account Id,#subdir/attachment2.doc
26
Load Binary Attachments Create a Zip Batch File with Binary Attachments
</sObject>
</sObjects>
SEE ALSO:
Create a Zip Batch File with Binary Attachments
SEE ALSO:
Create a request.txt File
27
Load Binary Attachments Create a Batch with Binary Attachments
Note: The batches for this job contain data in CSV format, so the contentType field is set to ZIP_CSV. For XML or JSON
batches, use ZIP_XML or ZIP_JSON, respectively.
3. Note the value of the job ID returned in the <id> element. Use this ID in subsequent operations.
SEE ALSO:
Create a Batch with Binary Attachments
Create a Job
28
Load Binary Attachments Create a Batch with Binary Attachments
Note: The Content-type for the POST request is zip/csv. For XML or JSON batches, use zip/xml or zip/json instead.
Salesforce does not parse the CSV content or otherwise validate the batch until later. The response only acknowledges that the batch
was received.
3. Note the value of the batch ID returned in the <id> element. You can use this batch ID later to check the status of the batch.
For details on proceeding to close the associated job, check batch status, and retrieve batch results, see the Quick Start.
SEE ALSO:
Create a Job for Batches with Binary Attachments
Add a Batch to a Job
29
CHAPTER 6 Request Basics
In this chapter ... Here are some basics about Bulk API requests, including the format of URIs used to perform operations
and details on how to authenticate requests using a session header.
• About URIs
• Set a Session Header
30
Request Basics About URIs
About URIs
You send HTTP requests to a URI to perform operations with Bulk API.
The URI where you send HTTP requests has the following format:
Web_Services_SOAP_endpoint_instance_name/services/async/APIversion/Resource_address
Think of the part of the URI through the API version as a base URI which is used for all operations. The part after the API version
(Resource_address) varies depending on the job or batch being processed. For example, if you're working with version 44.0 of
Bulk API on your instance, your base URI would be https://yourInstance.salesforce.com/services/async/44.0.
The instance name for your organization is returned in the LoginResult serverUrl field.
SEE ALSO:
Work with Jobs
Work with Batches
SEE ALSO:
Quick Start
Sample Client Application Using Java
31
CHAPTER 7 Work with Jobs
In this chapter ... You process a set of records by creating a job that contains one or more batches. The job specifies which
object is being processed and what type of operation is being used.
• Create a Job
A job is represented by the JobInfo resource. This resource is used to create a new job, get status for an
• Monitor a Job
existing job, and change status for a job.
• Close a Job
Note: Salesforce provides an additional API, Bulk API 2.0, which uses the REST API framework to
• Get Job Details
provide similar capabilities to Bulk API. Bulk API 2.0 simplifies the job creation and monitoring
• Abort a Job
process. For more information on Bulk API 2.0, see the Bulk API 2.0 Developer Guide.
• Job and Batch
Lifespan
32
Work with Jobs Create a Job
Create a Job
Create a job by sending a POST request to the following URI. The request body identifies the type of object processed in all associated
batches.
URI
https://instance_name—api.salesforce.com/services/async/APIversion/job
Example XML request body
<?xml version="1.0" encoding="UTF-8"?>
<jobInfo
xmlns="http://www.force.com/2009/06/asyncapi/dataload">
<operation>insert</operation>
<object>Account</object>
<contentType>CSV</contentType>
</jobInfo>
33
Work with Jobs Monitor a Job
In these samples, the contentType field indicates that the batches associated with the job are in CSV format. For alternative options,
such as XML or JSON, see JobInfo on page 72.
Warning: The operation value must be all lower case. For example, you get an error if you use INSERT instead of insert.
SEE ALSO:
Create a Job for Batches with Binary Attachments
Get Job Details
Close a Job
Abort a Job
Add a Batch to a Job
Job and Batch Lifespan
Bulk API Limits
About URIs
JobInfo
Quick Start
Monitor a Job
You can monitor a Bulk API job in Salesforce. The monitoring page tracks jobs and batches created by any client application, including
Data Loader or any client application that you write.
34
Work with Jobs Close a Job
To track the status of bulk data load jobs that are in progress or recently completed, enter Bulk Data Load Jobs in the Quick
Find box, then select Bulk Data Load Jobs. This page allows you to monitor the progress of current jobs and the results of recent
jobs.
For more information, see “Monitoring Bulk Data Load Jobs” in the Salesforce online help.
SEE ALSO:
Create a Job
Get Job Details
Close a Job
Abort a Job
Add a Batch to a Job
Job and Batch Lifespan
Bulk API Limits
Data Loader Guide
Close a Job
Close a job by sending a POST request to the following URI. The request URI identifies the job to close. When a job is closed, no more
batches can be added.
URI
https://instance_name—api.salesforce.com/services/async/APIversion/job/jobId
Example XML request body
<?xml version="1.0" encoding="UTF-8"?>
<jobInfo
xmlns="http://www.force.com/2009/06/asyncapi/dataload">
<state>Closed</state>
</jobInfo>
35
Work with Jobs Close a Job
<numberRecordsProcessed>2</numberRecordsProcessed>
<numberRetries>0</numberRetries>
<apiVersion>36.0</apiVersion>
<numberRecordsFailed>0</numberRecordsFailed>
<totalProcessingTime>3647</totalProcessingTime>
<apiActiveProcessingTime>2136</apiActiveProcessingTime>
<apexProcessingTime>0</apexProcessingTime>
</jobInfo>
SEE ALSO:
Create a Job
Monitor a Job
Get Job Details
Abort a Job
Job and Batch Lifespan
Bulk API Limits
About URIs
JobInfo
Quick Start
36
Work with Jobs Get Job Details
37
Work with Jobs Abort a Job
"numberRetries" : 0,
"object" : "Account",
"operation" : "insert",
"state" : "Open",
"systemModstamp" : "2015-12-15T20:45:25.000+0000",
"totalProcessingTime" : 0
}
SEE ALSO:
Create a Job
Monitor a Job
Close a Job
Abort a Job
Add a Batch to a Job
Job and Batch Lifespan
Bulk API Limits
About URIs
JobInfo
Quick Start
Abort a Job
Abort an existing job by sending a POST request to the following URI. The request URI identifies the job to abort. When a job is aborted,
no more records are processed. If changes to data have already been committed, they aren’t rolled back.
URI
https://instance_name—api.salesforce.com/services/async/APIversion/job/jobId
Example XML request body
<?xml version="1.0" encoding="UTF-8"?>
<jobInfo
xmlns="http://www.force.com/2009/06/asyncapi/dataload">
<state>Aborted</state>
</jobInfo>
38
Work with Jobs Abort a Job
<numberBatchesQueued>0</numberBatchesQueued>
<numberBatchesInProgress>0</numberBatchesInProgress>
<numberBatchesCompleted>1</numberBatchesCompleted>
<numberBatchesFailed>0</numberBatchesFailed>
<numberBatchesTotal>1</numberBatchesTotal>
<numberRecordsProcessed>2</numberRecordsProcessed>
<numberRetries>0</numberRetries>
<apiVersion>36.0</apiVersion>
<numberRecordsFailed>0</numberRecordsFailed>
<totalProcessingTime>3647</totalProcessingTime>
<apiActiveProcessingTime>2136</apiActiveProcessingTime>
<apexProcessingTime>0</apexProcessingTime>
</jobInfo>
39
Work with Jobs Job and Batch Lifespan
"totalProcessingTime" : 2870
}
SEE ALSO:
Get Job Details
Create a Job
Monitor a Job
Close a Job
Job and Batch Lifespan
Bulk API Limits
About URIs
JobInfo
SEE ALSO:
Create a Job
Monitor a Job
Get Job Details
Close a Job
Abort a Job
Add a Batch to a Job
Bulk API Limits
About URIs
JobInfo
Quick Start
40
CHAPTER 8 Work with Batches
In this chapter ... A batch is a set of records sent to the server in an HTTP POST request. Each batch is processed
independently by the server, not necessarily in the order it is received.
• Add a Batch to a Job
A batch is created by submitting a CSV, XML, or JSON representation of a set of records and any references
• Monitor a Batch
to binary attachments in an HTTP POST request. When created, the status of a batch is represented by
• Get Information for a a BatchInfo resource. When a batch is complete, the result for each record is available in a result set
Batch resource.
• Get Information for
Batches may be processed in parallel. It's up to the client to decide how to divide the entire data set into
All Batches in a Job
a suitable number of batches.
• Interpret Batch State
Batch sizes should be adjusted based on processing times. Start with 5000 records and adjust the batch
• Get a Batch Request
size based on processing time. If it takes more than five minutes to process a batch, it may be beneficial
• Get Batch Results to reduce the batch size. If it takes a few seconds, the batch size should be increased. If you get a timeout
• Handle Failed error when processing a batch, split your batch into smaller batches, and try again.
Records in Batches
Note: Salesforce provides an additional API, Bulk API 2.0, which uses the REST API framework to
provide similar capabilities to Bulk API. Bulk API 2.0 removes the need for creating and monitoring
batches, and lets you load record data for a job directly. For more information on Bulk API 2.0, see
the Bulk API 2.0 Developer Guide.
41
Work with Batches Add a Batch to a Job
Note: The API version in the URI for all batch operations must match the API version for the associated job.
In this sample, the batch data is in XML format because the contentType field of the associated job was set to XML. For alternative
formats for batch data, such as CSV or JSON, see JobInfo on page 72.
Example XML response body
<?xml version="1.0" encoding="UTF-8"?>
<batchInfo
xmlns="http://www.force.com/2009/06/asyncapi/dataload">
<id>751D0000000004rIAA</id>
<jobId>750D0000000002lIAA</jobId>
<state>Queued</state>
<createdDate>2009-04-14T18:15:59.000Z</createdDate>
<systemModstamp>2009-04-14T18:15:59.000Z</systemModstamp>
<numberRecordsProcessed>0</numberRecordsProcessed>
<numberRecordsFailed>0</numberRecordsFailed>
<totalProcessingTime>0</totalProcessingTime>
<apiActiveProcessingTime>0</apiActiveProcessingTime>
<apexProcessingTime>0</apexProcessingTime>
</batchInfo>
42
Work with Batches Monitor a Batch
In this sample, the batch data is in JSON format because the contentType field of the associated job was set to JSON.
Example JSON response body
{
"apexProcessingTime":0,
"apiActiveProcessingTime":0,
"createdDate":"2015-12-15T21:56:43.000+0000",
"id":"751D00000004YGZIA2",
"jobId":"750D00000004SkVIAU",
"numberRecordsFailed":0,
"numberRecordsProcessed":0,
"state":"Queued",
"systemModstamp":"2015-12-15T21:56:43.000+0000",
"totalProcessingTime":0
}
Note: You can add batch jobs using non–Bulk API–compliant CSV files. See Map Data Fields on page 100.
SEE ALSO:
Create a Batch with Binary Attachments
Get Information for a Batch
Monitor a Batch
Get Information for All Batches in a Job
Interpret Batch State
Get a Batch Request
Get Batch Results
Work with Jobs
Job and Batch Lifespan
Bulk API Limits
About URIs
BatchInfo
Quick Start
Monitor a Batch
You can monitor a Bulk API batch in Salesforce.
To track the status of bulk data load jobs and their associated batches, from Setup, enter Bulk Data Load Jobs in the Quick
Find box, then select Bulk Data Load Jobs. Click the Job ID to view the job detail page.
The job detail page includes a related list of all the batches for the job. The related list provides View Request and View Response links
for each batch. If the batch is a CSV file, the links return the request or response in CSV format. If the batch is an XML or JSON file, the
links return the request or response in XML or JSON format, respectively. These links are available for batches created in API version 19.0
and later. For Bulk V2 type jobs, batch information is unavailable.
43
Work with Batches Get Information for a Batch
For more information, see “Monitoring Bulk Data Load Jobs” in the Salesforce online help.
SEE ALSO:
Get Information for a Batch
Add a Batch to a Job
Get Information for All Batches in a Job
Interpret Batch State
Get a Batch Request
Get Batch Results
Handle Failed Records in Batches
Work with Jobs
Job and Batch Lifespan
Bulk API Limits
About URIs
BatchInfo
Quick Start
44
Work with Batches Get Information for All Batches in a Job
"id" : "751D00000004YGeIAM",
"jobId" : "750D00000004SkVIAU",
"numberRecordsFailed" : 0,
"numberRecordsProcessed" : 0,
"state" : "InProgress",
"systemModstamp" : "2015-12-15T22:52:49.000+0000",
"totalProcessingTime" : 0
}
SEE ALSO:
Add a Batch to a Job
Monitor a Batch
Get Information for All Batches in a Job
Interpret Batch State
Get a Batch Request
Get Batch Results
Job and Batch Lifespan
Bulk API Limits
BatchInfo
About URIs
Work with Jobs
Quick Start
45
Work with Batches Get Information for All Batches in a Job
<totalProcessingTime>0</totalProcessingTime>
<apiActiveProcessingTime>0</apiActiveProcessingTime>
<apexProcessingTime>0</apexProcessingTime>
</batchInfo>
<batchInfo>
<id>751D0000000004sIAA</id>
<jobId>750D0000000002lIAA</jobId>
<state>InProgress</state>
<createdDate>2009-04-14T18:16:00.000Z</createdDate>
<systemModstamp>2009-04-14T18:16:09.000Z</systemModstamp>
<numberRecordsProcessed>800</numberRecordsProcessed>
<numberRecordsFailed>0</numberRecordsFailed>
<totalProcessingTime>5870</totalProcessingTime>
<apiActiveProcessingTime>0</apiActiveProcessingTime>
<apexProcessingTime>2166</apexProcessingTime>
</batchInfo>
</batchInfoList>
46
Work with Batches Interpret Batch State
]
}
SEE ALSO:
Add a Batch to a Job
Monitor a Batch
Get Information for a Batch
Interpret Batch State
Get a Batch Request
Get Batch Results
Job and Batch Lifespan
Bulk API Limits
BatchInfo
About URIs
Work with Jobs
Quick Start
47
Work with Batches Get a Batch Request
After the original batch is changed to this state, you can monitor the subsequent batches and retrieve each batch’s results when it’s
completed.
SEE ALSO:
Add a Batch to a Job
Monitor a Batch
Get Information for All Batches in a Job
Get a Batch Request
Get Batch Results
Handle Failed Records in Batches
Job and Batch Lifespan
Bulk API Limits
BatchInfo
About URIs
Work with Jobs
Quick Start
48
Work with Batches Get Batch Results
SEE ALSO:
Get Information for a Batch
Monitor a Batch
Get Information for All Batches in a Job
Interpret Batch State
Get Batch Results
Work with Jobs
Job and Batch Lifespan
Bulk API Limits
About URIs
BatchInfo
Quick Start
49
Work with Batches Get Batch Results
50
Work with Batches Handle Failed Records in Batches
Note: The batch result indicates that the last record was not processed successfully because the LastName field was
missing. The Error column includes error information. You must look at the Success field for each result row to ensure
that all rows were processed successfully. For more information, see Handle Failed Records in Batches on page 51.
SEE ALSO:
Add a Batch to a Job
Monitor a Batch
Get a Batch Request
Get Information for a Batch
Get Information for All Batches in a Job
Interpret Batch State
Job and Batch Lifespan
Bulk API Limits
BatchInfo
About URIs
Work with Jobs
Quick Start
51
Work with Batches Handle Failed Records in Batches
d. Write the contents of the corresponding record in the batch request to an error file on your computer. Append the information
from the Error column. If you don't cache the batch request that you submitted, you can retrieve the batch request from
Salesforce.
After you have examined each result record, you can manually fix each record in the error file and submit these records in a new batch.
Repeat the earlier steps to check that each record is processed successfully.
SEE ALSO:
Add a Batch to a Job
Errors
Bulk API Limits
52
CHAPTER 9 Bulk Query
In this chapter ... Use bulk query to efficiently query large data sets and reduce the number of API requests. A bulk query
can retrieve up to 15 GB of data, divided into 15 1-GB files. The data formats supported are CSV, XML,
• How Bulk Queries and JSON.
Are Processed
• Use Bulk Query
• Walk Through a Bulk
Query Sample
• Walk Through a Bulk
Query Sample Using
PK Chunking
53
Bulk Query How Bulk Queries Are Processed
SEE ALSO:
Use Bulk Query
PK Chunking Header
Walk Through a Bulk Query Sample
54
Bulk Query Use Bulk Query
55
Bulk Query Use Bulk Query
<createdDate>2009-09-01T17:44:45.000Z</createdDate>
<systemModstamp>2009-09-01T17:44:45.000Z</systemModstamp>
<numberRecordsProcessed>0</numberRecordsProcessed>
<numberRecordsFailed>0</numberRecordsFailed>
<totalProcessingTime>0</totalProcessingTime>
<apiActiveProcessingTime>0</apiActiveProcessingTime>
<apexProcessingTime>0</apexProcessingTime>
</batchInfo>
Get Batch Information for All Batches in a Job HTTP Request (used when PK chunking is enabled)
GET baseURI/job/750x00000000014/batch
X-SFDC-Session: 4f1a00D30000000K7zB!ARUAQDqAHcM...
Get Batch Information for All Batches in a Job HTTP Response Body
<?xml version="1.0" encoding="UTF-8"?><batchInfoList
xmlns="http://www.force.com/2009/06/asyncapi/dataload">
<batchInfo>
<id>751D00000004YjwIAE</id>
<jobId>750D00000004T5OIAU</jobId>
<state>NotProcessed</state>
<createdDate>2011-03-10T00:59:47.000Z</createdDate>
<systemModstamp>2011-03-10T01:00:19.000Z</systemModstamp>
<numberRecordsProcessed>0</numberRecordsProcessed>
<numberRecordsFailed>0</numberRecordsFailed>
<totalProcessingTime>0</totalProcessingTime>
<apiActiveProcessingTime>0</apiActiveProcessingTime>
<apexProcessingTime>0</apexProcessingTime>
</batchInfo>
<batchInfo>
<id>751D00000004Yk1IAE</id>
<jobId>750D00000004T5OIAU</jobId>
<state>Completed</state>
<createdDate>2011-03-10T00:59:47.000Z</createdDate>
<systemModstamp>2011-03-10T01:00:19.000Z</systemModstamp>
<numberRecordsProcessed>100000</numberRecordsProcessed>
<numberRecordsFailed>0</numberRecordsFailed>
<totalProcessingTime>1000</totalProcessingTime>
<apiActiveProcessingTime>1000</apiActiveProcessingTime>
<apexProcessingTime>0</apexProcessingTime>
</batchInfo>
<batchInfo>
<id>751D00000004Yk2IAE</id>
<jobId>750D00000004T5OIAU</jobId>
<state>Completed</state>
<createdDate>2011-03-10T00:59:47.000Z</createdDate>
<systemModstamp>2011-03-10T01:00:19.000Z</systemModstamp>
<numberRecordsProcessed>100000</numberRecordsProcessed>
<numberRecordsFailed>0</numberRecordsFailed>
<totalProcessingTime>1000</totalProcessingTime>
<apiActiveProcessingTime>1000</apiActiveProcessingTime>
<apexProcessingTime>0</apexProcessingTime>
</batchInfo>
<batchInfo>
56
Bulk Query Use Bulk Query
<id>751D00000004Yk6IAE</id>
<jobId>750D00000004T5OIAU</jobId>
<state>Completed</state>
<createdDate>2011-03-10T00:59:47.000Z</createdDate>
<systemModstamp>2011-03-10T01:00:19.000Z</systemModstamp>
<numberRecordsProcessed>100000</numberRecordsProcessed>
<numberRecordsFailed>0</numberRecordsFailed>
<totalProcessingTime>1000</totalProcessingTime>
<apiActiveProcessingTime>1000</apiActiveProcessingTime>
<apexProcessingTime>0</apexProcessingTime>
</batchInfo>
<batchInfo>
<id>751D00000004Yk7IAE</id>
<jobId>750D00000004T5OIAU</jobId>
<state>Completed</state>
<createdDate>2011-03-10T00:59:47.000Z</createdDate>
<systemModstamp>2011-03-10T01:00:19.000Z</systemModstamp>
<numberRecordsProcessed>50000</numberRecordsProcessed>
<numberRecordsFailed>0</numberRecordsFailed>
<totalProcessingTime>500</totalProcessingTime>
<apiActiveProcessingTime>500</apiActiveProcessingTime>
<apexProcessingTime>0</apexProcessingTime>
</batchInfo>
</batchInfoList>
57
Bulk Query Use Bulk Query
job.setOperation(OperationEnum.query);
job.setConcurrencyMode(ConcurrencyMode.Parallel);
job.setContentType(ContentType.CSV);
job = bulkConnection.createJob(job);
assert job.getId() != null;
job = bulkConnection.getJobStatus(job.getId());
String query =
"SELECT Name, Id, Description__c FROM Merchandise__c";
58
Bulk Query Walk Through a Bulk Query Sample
if (info.getState() == BatchStateEnum.Completed) {
QueryResultList list =
bulkConnection.getQueryResultList(job.getId(),
info.getId());
queryResults = list.getResult();
break;
} else if (info.getState() == BatchStateEnum.Failed) {
System.out.println("-------------- failed ----------"
+ info);
break;
} else {
System.out.println("-------------- waiting ----------"
+ info);
}
}
if (queryResults != null) {
for (String resultId : queryResults) {
bulkConnection.getQueryResultStream(job.getId(),
info.getId(), resultId);
}
}
} catch (AsyncApiException aae) {
aae.printStackTrace();
} catch (InterruptedException ie) {
ie.printStackTrace();
}
}
SEE ALSO:
How Bulk Queries Are Processed
PK Chunking Header
Walk Through a Bulk Query Sample
59
Bulk Query Walk Through a Bulk Query Sample
Create a Job
1. Create a file called create-job.xml containing the following text.
<?xml version="1.0" encoding="UTF-8"?>
<jobInfo
xmlns="http://www.force.com/2009/06/asyncapi/dataload">
<operation>query</operation>
<object>Account</object>
<concurrencyMode>Parallel</concurrencyMode>
<contentType>CSV</contentType>
</jobInfo>
2. Using a command-line window, execute the following cURL command to create a job.
curl -H "X-SFDC-Session: sessionId" -H "Content-Type: application/xml; charset=UTF-8"
-d @create-job.xml https://instance.salesforce.com/services/async/44.0/job
instance is the portion of the <serverUrl> element and sessionId is the <sessionId> element that you noted
in the login response.
Salesforce returns an XML response with data such as the following.
<?xml version="1.0" encoding="UTF-8"?>
<jobInfo
xmlns="http://www.force.com/2009/06/asyncapi/dataload">
<id>750x000000009tvAAA</id>
<operation>query</operation>
<object>Account</object>
<createdById>005x0000001WR0lAAG</createdById>
<createdDate>2016-01-10T00:53:19.000Z</createdDate>
<systemModstamp>2016-01-10T00:53:19.000Z</systemModstamp>
<state>Open</state>
<concurrencyMode>Parallel</concurrencyMode>
<contentType>CSV</contentType>
<numberBatchesQueued>0</numberBatchesQueued>
<numberBatchesInProgress>0</numberBatchesInProgress>
<numberBatchesCompleted>0</numberBatchesCompleted>
<numberBatchesFailed>0</numberBatchesFailed>
<numberBatchesTotal>0</numberBatchesTotal>
<numberRecordsProcessed>0</numberRecordsProcessed>
<numberRetries>0</numberRetries>
<apiVersion>36.0</apiVersion>
<numberRecordsFailed>0</numberRecordsFailed>
<totalProcessingTime>0</totalProcessingTime>
<apiActiveProcessingTime>0</apiActiveProcessingTime>
<apexProcessingTime>0</apexProcessingTime>
</jobInfo>
60
Bulk Query Walk Through a Bulk Query Sample
2. Using a command-line window, execute the following cURL command to add a batch to the job:
curl -d @query.txt -H "X-SFDC-Session: sessionId" -H "Content-Type: text/csv;
charset=UTF-8" https://instance.salesforce.com/services/async/44.0/job/jobId/batch
jobId is the job ID returned in the response to the job createion.
Salesforce returns an XML response with data such as the following.
<?xml version="1.0" encoding="UTF-8"?>
<batchInfo
xmlns="http://www.force.com/2009/06/asyncapi/dataload">
<id>751x000000009vwAAA</id>
<jobId>750x000000009tvAAA</jobId>
<state>Queued</state>
<createdDate>2016-01-10T00:59:47.000Z</createdDate>
<systemModstamp>2016-01-10T00:59:47.000Z</systemModstamp>
<numberRecordsProcessed>0</numberRecordsProcessed>
<numberRecordsFailed>0</numberRecordsFailed>
<totalProcessingTime>0</totalProcessingTime>
<apiActiveProcessingTime>0</apiActiveProcessingTime>
<apexProcessingTime>0</apexProcessingTime>
</batchInfo>
Note: When adding a batch to a bulk query job, the Content-Type in the header for the request must be either text/csv,
application/xml, or application/json, depending on the content type specified when the job was created.
The actual SOQL statement supplied for the batch is in plain text format.
61
Bulk Query Walk Through a Bulk Query Sample
<apiVersion>36.0</apiVersion>
<numberRecordsFailed>0</numberRecordsFailed>
<totalProcessingTime>0</totalProcessingTime>
<apiActiveProcessingTime>0</apiActiveProcessingTime>
<apexProcessingTime>0</apexProcessingTime>
</jobInfo>
2. Using a command-line window, execute the following cURL command to check the batch status.
curl -H "X-SFDC-Session: sessionId"
https://instance.salesforce.com/services/async/44.0/job/jobId/batch/batchId
batchId is the batch ID in the response to the batch creation.
Salesforce returns an XML response with data such as the following.
<?xml version="1.0" encoding="UTF-8"?>
<batchInfo
xmlns="http://www.force.com/2009/06/asyncapi/dataload">
<id>751x000000009vwAAA</id>
<jobId>750x000000009tvAAA</jobId>
<state>Completed</state>
<createdDate>2016-01-10T00:59:47.000Z</createdDate>
<systemModstamp>2016-01-10T01:00:19.000Z</systemModstamp>
<numberRecordsProcessed>10</numberRecordsProcessed>
<numberRecordsFailed>0</numberRecordsFailed>
<totalProcessingTime>0</totalProcessingTime>
<apiActiveProcessingTime>0</apiActiveProcessingTime>
<apexProcessingTime>0</apexProcessingTime>
</batchInfo>
2. Using the command-line window, execute the following cURL command to retrieve the results of the query.
curl -H "X-SFDC-Session: sessionId"
https://instance.salesforce.com/services/async/44.0/job/jobId/batch/batchId/result/resultId
resultId is the result ID in the response to the batch result list request.
Salesforce returns a CSV response with data such as the following.
"Id","Name"
"001x000xxx4TU4JAAW","name161268--1296595660659"
62
Bulk Query Walk Through a Bulk Query Sample
"001x000xxx4TU4KAAW","name161269--1296595660659"
"001x000xxx4TU4LAAW","name161270--1296595660659"
"001x000xxx4TU4MAAW","name161271--1296595660659"
"001x000xxx4TU4NAAW","name161272--1296595660659"
"001x000xxx4TU4OAAW","name161273--1296595660659"
"001x000xxx4TU4PAAW","name161274--1296595660659"
"001x000xxx4TU4QAAW","name161275--1296595660659"
"001x000xxx4TU4RAAW","name161276--1296595660659"
"001x000xxx4TU4SAAW","name161277--1296595660659"
2. Using a command-line window, execute the following cURL command to close the job.
curl -H "X-SFDC-Session: sessionId" -H "Content-Type: text/csv; charset=UTF-8" -d
@close-job.xml https://instance.salesforce.com/services/async/44.0/job/jobId
Salesforce returns an XML response with data such as the following.
<?xml version="1.0" encoding="UTF-8"?>
<jobInfo
xmlns="http://www.force.com/2009/06/asyncapi/dataload">
<id>750x000000009tvAAA</id>
<operation>query</operation>
<object>Account</object>
<createdById>005x0000001WR0lAAG</createdById>
<createdDate>2016-01-10T00:53:19.000Z</createdDate>
<systemModstamp>2016-01-10T00:53:19.000Z</systemModstamp>
<state>Closed</state>
<concurrencyMode>Parallel</concurrencyMode>
<contentType>CSV</contentType>
<numberBatchesQueued>0</numberBatchesQueued>
<numberBatchesInProgress>0</numberBatchesInProgress>
<numberBatchesCompleted>1</numberBatchesCompleted>
<numberBatchesFailed>0</numberBatchesFailed>
<numberBatchesTotal>1</numberBatchesTotal>
<numberRecordsProcessed>10</numberRecordsProcessed>
<numberRetries>0</numberRetries>
<apiVersion>36.0</apiVersion>
<numberRecordsFailed>0</numberRecordsFailed>
<totalProcessingTime>0</totalProcessingTime>
<apiActiveProcessingTime>0</apiActiveProcessingTime>
63
Bulk Query Walk Through a Bulk Query Sample Using PK Chunking
<apexProcessingTime>0</apexProcessingTime>
</jobInfo>
SEE ALSO:
How Bulk Queries Are Processed
Use Bulk Query
Walk Through a Bulk Query Sample Using PK Chunking
2. Using a command-line window, execute the following cURL command to create a job with PK chunking enabled.
curl -H "X-SFDC-Session: sessionId" -H "Content-Type: application/xml; charset=UTF-8"
-H "Sforce-Enable-PKChunking: true" -d @create-job.xml
https://instance.salesforce.com/services/async/44.0/job
instance is the portion of the <serverUrl> element, and sessionId is the <sessionId> element that you noted
in the login response.
Note: Salesforce recommends that you enable PK chunking when querying tables with more than 10 million records or when
a bulk query consistently times out. For the purposes of this example, if you’re querying significantly fewer records, set
chunkSize to a number smaller than the number of records you’re querying. For example,
Sforce-Enable-PKChunking: chunkSize=1000. This way, you get to see PK chunking in action, and the query
is split into multiple batches.
Salesforce returns an XML response with data such as the following.
<?xml version="1.0" encoding="UTF-8"?>
<jobInfo
xmlns="http://www.force.com/2009/06/asyncapi/dataload">
64
Bulk Query Walk Through a Bulk Query Sample Using PK Chunking
<id>750x000000009tvAAA</id>
<operation>query</operation>
<object>Account</object>
<createdById>005x0000001WR0lAAG</createdById>
<createdDate>2016-01-10T00:53:19.000Z</createdDate>
<systemModstamp>2016-01-10T00:53:19.000Z</systemModstamp>
<state>Open</state>
<concurrencyMode>Parallel</concurrencyMode>
<contentType>CSV</contentType>
<numberBatchesQueued>0</numberBatchesQueued>
<numberBatchesInProgress>0</numberBatchesInProgress>
<numberBatchesCompleted>0</numberBatchesCompleted>
<numberBatchesFailed>0</numberBatchesFailed>
<numberBatchesTotal>0</numberBatchesTotal>
<numberRecordsProcessed>0</numberRecordsProcessed>
<numberRetries>0</numberRetries>
<apiVersion>36.0</apiVersion>
<numberRecordsFailed>0</numberRecordsFailed>
<totalProcessingTime>0</totalProcessingTime>
<apiActiveProcessingTime>0</apiActiveProcessingTime>
<apexProcessingTime>0</apexProcessingTime>
</jobInfo>
2. Using a command-line window, execute the following cURL command to add a batch to the job.
curl -d @query.txt -H "X-SFDC-Session: sessionId" -H "Content-Type: text/csv;
charset=UTF-8" https://instance.salesforce.com/services/async/44.0/job/jobId/batch
jobId is the job ID returned in the response to the job creation.
Salesforce returns an XML response with data such as the following.
<?xml version="1.0" encoding="UTF-8"?>
<batchInfo
xmlns="http://www.force.com/2009/06/asyncapi/dataload">
<id>751x000000009vwAAA</id>
<jobId>750x000000009tvAAA</jobId>
<state>Queued</state>
<createdDate>2016-01-10T00:59:47.000Z</createdDate>
<systemModstamp>2016-01-10T00:59:47.000Z</systemModstamp>
<numberRecordsProcessed>0</numberRecordsProcessed>
<numberRecordsFailed>0</numberRecordsFailed>
<totalProcessingTime>0</totalProcessingTime>
<apiActiveProcessingTime>0</apiActiveProcessingTime>
<apexProcessingTime>0</apexProcessingTime>
</batchInfo>
65
Bulk Query Walk Through a Bulk Query Sample Using PK Chunking
Note: When adding a batch to a bulk query job, the Content-Type in the header for the request must be either text/csv,
application/xml, or application/json, depending on the content type specified when the job was created.
The actual SOQL statement supplied for the batch is in plain text format.
Because PK chunking is enabled, extra batches are automatically created to process the entire query.
2. Using a command-line window, execute the following cURL command to check the status of the original batch.
curl -H "X-SFDC-Session: sessionId"
https://instance.salesforce.com/services/async/44.0/job/jobId/batch/batchId
batchId is the batch ID in the response to the batch creation.
Salesforce returns an XML response with data such as the following.
<?xml version="1.0" encoding="UTF-8"?>
<batchInfo
xmlns="http://www.force.com/2009/06/asyncapi/dataload">
<id>751x000000009vwAAA</id>
<jobId>750x000000009tvAAA</jobId>
<state>Not Processed</state>
66
Bulk Query Walk Through a Bulk Query Sample Using PK Chunking
<createdDate>2016-01-10T00:59:47.000Z</createdDate>
<systemModstamp>2016-01-10T01:00:19.000Z</systemModstamp>
<numberRecordsProcessed>0</numberRecordsProcessed>
<numberRecordsFailed>0</numberRecordsFailed>
<totalProcessingTime>0</totalProcessingTime>
<apiActiveProcessingTime>0</apiActiveProcessingTime>
<apexProcessingTime>0</apexProcessingTime>
</batchInfo>
Because PK chunking is enabled, the original batch is given a state of Not Processed. The query is processed in the remaining
batches.
67
Bulk Query Walk Through a Bulk Query Sample Using PK Chunking
<numberRecordsFailed>0</numberRecordsFailed>
<totalProcessingTime>1000</totalProcessingTime>
<apiActiveProcessingTime>1000</apiActiveProcessingTime>
<apexProcessingTime>0</apexProcessingTime>
</batchInfo>
<batchInfo>
<id>751D00000004Yk6IAE</id>
<jobId>750D00000004T5OIAU</jobId>
<state>Completed</state>
<createdDate>2016-01-10T00:59:47.000Z</createdDate>
<systemModstamp>2016-01-10T01:00:19.000Z</systemModstamp>
<numberRecordsProcessed>100000</numberRecordsProcessed>
<numberRecordsFailed>0</numberRecordsFailed>
<totalProcessingTime>1000</totalProcessingTime>
<apiActiveProcessingTime>1000</apiActiveProcessingTime>
<apexProcessingTime>0</apexProcessingTime>
</batchInfo>
<batchInfo>
<id>751D00000004Yk7IAE</id>
<jobId>750D00000004T5OIAU</jobId>
<state>Completed</state>
<createdDate>2016-01-10T00:59:47.000Z</createdDate>
<systemModstamp>2016-01-10T01:00:19.000Z</systemModstamp>
<numberRecordsProcessed>50000</numberRecordsProcessed>
<numberRecordsFailed>0</numberRecordsFailed>
<totalProcessingTime>500</totalProcessingTime>
<apiActiveProcessingTime>500</apiActiveProcessingTime>
<apexProcessingTime>0</apexProcessingTime>
</batchInfo>
</batchInfoList>
2. Using the command-line window, execute the following cURL command to retrieve the results of the query.
curl -H "X-SFDC-Session: sessionId"
https://instance.salesforce.com/services/async/44.0/job/jobId/batch/batchId/result/resultId
resultId is the result ID in the response to the batch result list request.
68
Bulk Query Walk Through a Bulk Query Sample Using PK Chunking
2. Using a command-line window, execute the following cURL command to close the job.
curl -H "X-SFDC-Session: sessionId" -H "Content-Type: text/csv; charset=UTF-8" -d
@close-job.xml https://instance.salesforce.com/services/async/44.0/job/jobId
Salesforce returns an XML response with data such as the following.
<?xml version="1.0" encoding="UTF-8"?>
<jobInfo
xmlns="http://www.force.com/2009/06/asyncapi/dataload">
<id>750x000000009tvAAA</id>
<operation>query</operation>
<object>Account</object>
<createdById>005x0000001WR0lAAG</createdById>
<createdDate>2016-01-10T00:53:19.000Z</createdDate>
<systemModstamp>2016-01-10T00:53:19.000Z</systemModstamp>
<state>Closed</state>
<concurrencyMode>Parallel</concurrencyMode>
<contentType>CSV</contentType>
<numberBatchesQueued>0</numberBatchesQueued>
<numberBatchesInProgress>0</numberBatchesInProgress>
<numberBatchesCompleted>4</numberBatchesCompleted>
<numberBatchesFailed>0</numberBatchesFailed>
<numberBatchesTotal>4</numberBatchesTotal>
<numberRecordsProcessed>350000</numberRecordsProcessed>
<numberRetries>0</numberRetries>
<apiVersion>36.0</apiVersion>
<numberRecordsFailed>0</numberRecordsFailed>
<totalProcessingTime>3500</totalProcessingTime>
<apiActiveProcessingTime>3500</apiActiveProcessingTime>
69
Bulk Query Walk Through a Bulk Query Sample Using PK Chunking
<apexProcessingTime>0</apexProcessingTime>
</jobInfo>
SEE ALSO:
How Bulk Queries Are Processed
Use Bulk Query
PK Chunking Header
Walk Through a Bulk Query Sample
70
CHAPTER 10 Reference
In this chapter ... These are the supported resources for the Bulk API, as well as details on errors and processing limits.
• Schema
• JobInfo
• BatchInfo
• Headers
• HTTP Status Codes
• Errors
• Bulk API Limits
71
Reference Schema
Schema
The Bulk API service is described by an XML Schema Document (XSD) file.
You can download the schema file for an API version by using the following URI:
Web_Services_SOAP_endpoint_instance_name/services/async/APIversion/AsyncApi.xsd
For example, if you're working with version 44.0 of the Bulk API on your own instance, the URI is:
https://yourInstance.salesforce.com/services/async/44.0/AsyncApi.xsd
The instance name for your organization is returned in the LoginResult serverUrl field.
SEE ALSO:
JobInfo
BatchInfo
Errors
JobInfo
A job contains one or more batches of data for you to submit to Salesforce for processing. When a job is created, Salesforce sets the job
state to Open.
You can create a new job, get information about a job, close a job, or abort a job using the JobInfo resource.
Fields
Name Type Request Description
apiVersion string Read only. Do not The API version of the job set in the URI when the job
set for new job. was created. The earliest supported version is 17.0.
apexProcessingTime long Do not specify for The number of milliseconds taken to process triggers
new job. and other processes related to the job data. This is the
sum of the equivalent times in all batches in the job.
This doesn't include the time used for processing
asynchronous and batch Apex operations. If there are
no triggers, the value is 0. See also
apiActiveProcessingTime and
totalProcessingTime.
This field is available in API version 19.0 and later.
72
Reference JobInfo
assignmentRuleId string Can't update after The ID of a specific assignment rule to run for a case or
creation. a lead. The assignment rule can be active or inactive.
The ID can be retrieved by using the SOAP-based SOAP
API to query the AssignmentRule object.
concurrencyMode ConcurrencyModeEnum The concurrency mode for the job. The valid values are:
• Parallel: Process batches in parallel mode. This
is the default value.
• Serial: Process batches in serial mode.
Processing in parallel can cause database
contention. When this is severe, the job can fail. If
you’re experiencing this issue, submit the job with
serial concurrency mode. This mode
guarantees that batches are processed one at a
time, but can significantly increase the processing
time.
contentType ContentType The content type for the job. The valid values are:
• CSV—data in CSV format (default and only
supported content type for Bulk V2 type jobs)
• JSON—data in JSON format
• XML—data in XML format (default option for Bulk
V1 type jobs)
• ZIP_CSV—data in CSV format in a zip file
containing binary attachments
• ZIP_JSON—data in JSON format in a zip file
containing binary attachments
• ZIP_XML—data in XML format in a zip file
containing binary attachments
createdById string System field The ID of the user who created this job. All batches
must be created by this same user.
createdDate dateTime System field The date and time in the UTC time zone when the job
was created.
73
Reference JobInfo
numberBatchesCompleted int Do not specify for The number of batches that have been completed for
new job. this job.
numberBatchesQueued int Do not specify for The number of batches queued for this job.
new job.
numberBatchesFailed int Do not specify for The number of batches that have failed for this job.
new job.
numberBatchesInProgress int Do not specify for The number of batches that are in progress for this job.
new job.
numberBatchesTotal int Do not specify for The number of total batches currently in the job. This
new job. value increases as more batches are added to the job.
When the job state is Closed or Failed, this
number represents the final total.
The job is complete when numberBatchesTotal
equals the sum of numberBatchesCompleted
and numberBatchesFailed.
numberRecordsFailed int Do not specify for The number of records that were not processed
new job. successfully in this job.
This field is available in API version 19.0 and later.
numberRecordsProcessed int Do not specify for The number of records already processed. This number
new job. increases as more batches are processed.
object string Required The object type for the data being processed. All data
in a job must be of a single object type.
operation OperationEnum Required The processing operation for all the batches in the job.
The valid values are:
• delete
• insert
• query (Bulk V1 type jobs only)
• queryall (Bulk V1 type jobs only)
• upsert
• update
74
Reference JobInfo
state JobStateEnum Required if The current state of processing for the job:
creating, closing, • Open: The job has been created, and data can be
or aborting a job. added to the job.
• Closed: No new data can be added to this job.
Data associated with the job may be processed
after a job is closed. You cannot edit or save a
closed job.
• Aborted: The job has been aborted. You can
abort a job if you created it or if you have the
“Manage Data Integrations” permission.
• Failed: The job has failed. Batches that were
successfully processed can't be rolled back. The
BatchInfoList contains a list of all batches for the
job. From the results of BatchInfoList, results can
be retrieved for completed batches. The results
indicate which records have been processed. The
numberRecordsFailed field contains the
number of records that were not processed
successfully.
systemModstamp dateTime System field Date and time in the UTC time zone when the job
finished.
75
Reference BatchInfo
SEE ALSO:
Work with Jobs
Quick Start
SOAP API Developer Guide
BatchInfo
A BatchInfo contains one batch of data for you to submit to Salesforce for processing.
BatchInfo
Name Type Request Description
apexProcessingTime long System The number of milliseconds taken to process triggers and other
field processes related to the batch data. If there are no triggers, the value
is 0. This doesn't include the time used for processing asynchronous
and batch Apex operations. See also
apiActiveProcessingTime and
totalProcessingTime.
This field is available in API version 19.0 and later.
apiActiveProcessingTime long System The number of milliseconds taken to actively process the batch, and
field includes apexProcessingTime. This doesn't include the time
the batch waited in the queue to be processed or the time required
for serialization and deserialization. See also
totalProcessingTime.
This field is available in API version 19.0 and later.
createdDate dateTime System The date and time in the UTC time zone when the batch was created.
field This is not the time processing began, but the time the batch was
added to the job.
id string Required The ID of the batch. May be globally unique, but does not have to
be.
jobId string Required The unique, 18–character ID for the job associated with this batch.
76
Reference BatchInfo
numberRecordsProcessed int System The number of records processed in this batch at the time the request
field was sent. This number increases as more batches are processed.
state BatchStateEnum System The current state of processing for the batch:
field • Queued: Processing of the batch has not started yet. If the job
associated with this batch is aborted, the batch isn’t processed
and its state is set to Not Processed.
• InProgress: The batch is being processed. If the job
associated with the batch is aborted, the batch is still processed
to completion. You must close the job associated with the batch
so that the batch can finish processing.
• Completed: The batch has been processed completely, and
the result resource is available. The result resource indicates if
some records have failed. A batch can be completed even if some
or all the records have failed. If a subset of records failed, the
successful records aren’t rolled back.
• Failed: The batch failed to process the full request due to an
unexpected error, such as the request is compressed with an
unsupported format, or an internal server error. The
stateMessage element could contain more details about
any failures. Even if the batch failed, some records could have
been completed successfully. The
numberRecordsProcessed field tells you how many
records were processed. The numberRecordsFailed field
contains the number of records that were not processed
successfully.
• Not Processed: The batch won’t be processed. This state
is assigned when a job is aborted while the batch is queued. For
bulk queries, if the job has PK chunking enabled, this state is
assigned to the original batch that contains the query when the
subsequent batches are created. After the original batch is
changed to this state, you can monitor the subsequent batches
and retrieve each batch’s results when it’s completed. Then you
can safely close the job.
stateMessage string System Contains details about the state. For example, if the state value
field is Failed, this field contains the reasons for failure. If there are
multiple failures, the message may be truncated. If so, fix the known
errors and re-submit the batch. Even if the batch failed, some records
could have been completed successfully.
systemModstamp dateTime System The date and time in the UTC time zone that processing ended. This
field is only valid when the state is Completed.
77
Reference Headers
HTTP BatchInfoList
Name Type Description
batchInfo BatchInfo One BatchInfo resource for each batch in the associated job. For the structure
of BatchInfo, see BatchInfo on page 76.
SEE ALSO:
Work with Batches
Interpret Batch State
Quick Start
SOAP API Developer Guide
Headers
These are custom HTTP request and response headers that are used for Bulk API.
• Content Type Header
• Batch Retry Header
• Line Ending Header
• PK Chunking Header
78
Reference Batch Retry Header
79
Reference PK Chunking Header
PK Chunking Header
Use the PK Chunking request header to enable automatic primary key (PK) chunking for a bulk query job. PK chunking splits bulk queries
on very large tables into chunks based on the record IDs, or primary keys, of the queried records.
Each chunk is processed as a separate batch that counts toward your daily batch limit, and you must download each batch’s results
separately. PK chunking works only with queries that don’t include SELECT clauses or conditions other than WHERE.
PK chunking is supported for the following objects: Account, Campaign, CampaignMember, Case, CaseHistory, Contact, Event, EventRelation,
Lead, LoginHistory, Opportunity, Task, User, and custom objects.
PK chunking works by adding record ID boundaries to the query with a WHERE clause, limiting the query results to a smaller chunk of
the total results. The remaining results are fetched with extra queries that contain successive boundaries. The number of records within
the ID boundaries of each chunk is referred to as the chunk size. The first query retrieves records between a specified starting ID and the
starting ID plus the chunk size. The next query retrieves the next chunk of records, and so on.
For example, let’s say you enable PK chunking for the following query on an Account table with 10,000,000 records.
SELECT Name FROM Account
Assuming a chunk size of 250,000 and a starting record ID of 001300000000000, the query is split into the following 40 queries.
Each query is submitted as a separate batch.
SELECT Name FROM Account WHERE Id >= 001300000000000 AND Id < 00130000000132G
SELECT Name FROM Account WHERE Id >= 00130000000132G AND Id < 00130000000264W
SELECT Name FROM Account WHERE Id >= 00130000000264W AND Id < 00130000000396m
...
SELECT Name FROM Account WHERE Id >= 00130000000euQ4 AND Id < 00130000000fxSK
Each query executes on a chunk of 250,000 records specified by the base-62 ID boundaries.
PK chunking is designed for extracting data from entire tables, but you can also use it for filtered queries. Because records could be
filtered from each query’s results, the number of returned results for each chunk can be less than the chunk size. Also, the IDs of soft-deleted
records are counted when the query is split into chunks, but the records are omitted from the results. Therefore, if soft-deleted records
fall within a given chunk’s ID boundaries, the number of returned results is less than the chunk size.
The default chunk size is 100,000, and the maximum size is 250,000. The default starting ID is the first record in the table. However, you
can specify a different starting ID to restart a job that failed between chunked batches.
When a query is successfully chunked, the original batch’s status shows as NOT_PROCESSED. If the chunking fails, the original batch’s
status shows as FAILED, but any chunked batches that were successfully queued during the chunking attempt are processed as
normal. When the original batch’s status is changed to NOT_PROCESSED, monitor the subsequent batches. You can retrieve the
results from each subsequent batch after it’s completed. Then you can safely close the job.
Salesforce recommends that you enable PK chunking when querying tables with more than 10 million records or when a bulk query
consistently times out. However, the effectiveness of PK chunking depends on the specifics of the query and the queried data.
80
Reference HTTP Status Codes
• chunkSize—Specifies the number of records within the ID boundaries for each chunk. The default is 100,000, and the
maximum size is 250,000. If the query contains filters or soft-deleted records, the number of returned results for each chunk
could be less than the chunk size.
• parent—Specifies the parent object when you’re enabling PK chunking for queries on sharing objects. The chunks are based
on the parent object’s records rather than the sharing object’s records. For example, when querying on AccountShare, specify
Account as the parent object. PK chunking is supported for sharing objects as long as the parent object is supported.
Similarly, for CaseHistory, specify Case as the parent object.
• startRow—Specifies the 15-character or 18-character record ID to be used as the lower boundary for the first chunk. Use this
parameter to specify a starting ID when restarting a job that failed between batches.
Example
Sforce-Enable-PKChunking: chunkSize=50000; startRow=00130000000xEftMGH
Errors
Operations that you perform with Bulk API might trigger error codes. The following list shows the most common error codes and the
Bulk API action that might have triggered them.
ClientInputError
The operation failed with an unknown client-side error.
For binary attachments, the request content is provided both as an input stream and an attachment.
ExceededQuota
The job or batch you tried to create exceeds the allowed number for the past 24 hour period.
FeatureNotEnabled
Bulk API is not enabled for this organization.
InvalidBatch
The batch ID specified in a batch update or query is invalid.
This error code is returned for binary attachments when the zip content is malformed or the following conditions occur:
81
Reference Errors
• The request.txt file can't be found, can't be read, is a directory, or contains invalid content.
• The decompressed size of a binary attachment is too large.
• The size of the zip file is too large.
• The total decompressed size of all the binary attachments is too large.
For more information about binary attachment limits, see Binary content on page 83.
InvalidJob
The job ID specified in a query or update for a job, or a create, update, or query for batches is invalid.
The user attempted to create a job using a zip content type in API version 19.0 or earlier.
InvalidJobState
The job state specified in a job update operation is invalid.
InvalidOperation
The operation specified in a URI for a job is invalid. Check the spelling of “job” in the URI.
InvalidSessionId
The session ID specified is invalid.
InvalidUrl
The URI specified is invalid.
InvalidUser
Either the user sending an Bulk API request doesn't have the correct permission, or the job or batch specified was created by another
user.
InvalidXML
XML contained in the request body is invalid.
Timeout
The connection timed out. This error is thrown if Salesforce takes too long to process a batch. For more information on timeout
limits, see Batch processing time on page 83. If you get a timeout error when processing a batch, split your batch into smaller
batches, and try again.
TooManyLockFailure
Too many lock failures while processing the current batch. This error may be returned during processing of a batch. To resolve,
analyze the batches for lock conflicts. See General Guidelines for Data Loads on page 13.
Unknown
Exception with unknown cause occurred.
In addition, Bulk API uses the same status codes and exception codes as SOAP API. For more information on these codes, see
“ExceptionCode” in the SOAP API Developer Guide.
SEE ALSO:
HTTP Status Codes
Handle Failed Records in Batches
82
Reference Bulk API Limits
Note: Bulk queries have an extra 2-minute limit for processing the query, which is separate from the batch processing limit.
See query Limits.
Binary content
• The length of any file name can’t exceed 512 bytes.
• A zip file can’t exceed 10 MB.
• The total size of the unzipped content can’t exceed 20 MB.
• A maximum of 1,000 files can be contained in a zip file. Directories don’t count toward this total.
83
Reference Bulk API Limits
Compression
The only valid compression value is gzip. Compression is optional, but strongly recommended. Compression doesn’t affect the
character limits defined in Batch size.
Job abort
Any user with correct permission can abort a job. Only the user who created a job can close it.
Job close
Only the user who created a job can close it. Any user with correct permission can abort a job.
Job content
Each job can specify one operation and one object. Batches associated with this job contain records of one object. Optionally, you
can specify serial processing mode, which is used only when previously submitted asynchronous jobs have accidentally produced
contention because of locks. Use only when advised by Salesforce.
Job external ID
You can't edit the value of an external ID field in JobInfo. When specifying an external ID, the operation must be upsert. If you try to
use it with create or update, an error is generated.
Job lifespan
Batches and jobs that are older than seven days are removed from the queue regardless of job status. The seven days are measured
from the youngest batch associated with a job, or the age of the job if there are no batches. You can’t create batches associated
with a job that is more than 24 hours old.
Job open time
The maximum time that a job can remain open is 24 hours. The Bulk API doesn't support clients that, for example, post one batch
every hour for many hours.
Job status in job history
After a job has completed, the job status and batch result sets are available for seven days after which this data is deleted permanently.
Job status change
When you submit a POST body with a change in job status, you can only specify the status field value. If operation or
entity field values are specified, an error occurs.
Portal users
Regardless of whether the “API Enabled” profile permission is granted, portal users (Customer Portal, Self-Service portal, and Partner
Portal) can't access Bulk API.
query Limits
Bulk API query has the following limitations:
Feature Functionality
Retrieved file size 1 GB
Number of retrieved files 15 files. If the query needs to return more than 15 files, add filters
to the query to return less data. Bulk batch sizes are not used for
bulk queries.
Number of attempts to query 15 attempts at 10 minutes each to process the batch. There is
also a 2-minute limit on the time to process the query. If more
than 15 attempts are made for the query, an error message of
“Tried more than fifteen times” is returned. If the query takes
more than 2 minutes to process, a QUERY_TIMEOUT error is
returned.
84
Reference Bulk API Limits
Feature Functionality
Length of time results are kept 7 days.
85
APPENDIX A Sample Client Application Using Java
Use this code sample to create a test client application that inserts a number of account records using the REST-based Bulk API.
In addition to the step-by-step instructions that follow, the end of this section provides the complete code for you, to make copying
and pasting easier.
86
Sample Client Application Using Java Walk Through the Sample Code
1. Log in to your Developer Edition Salesforce account. You must log in as an administrator or as a user who has the “Modify All Data”
permission. Logins are checked to ensure they are from a known IP address. For more information, see “Restrict Where and When
Users Can Log In to Salesforce” in the Salesforce online help.
2. From Setup, enter “API” in the Quick Find box, then select API.
3. Right-click Partner WSDL to display your browser's save options, and save the partner WSDL to a local directory. For information
about the partner WSDL, see Using the Partner WSDL.
4. Compile the partner API code from the WSDL using the WSC compile tool:
For example, if force-wsc-XX.X.X-uber.jar is installed in C:\salesforce\wsc, and the partner WSDL is saved to
C:\salesforce\wsdl\partner:
force-wsc-XX.X.X-uber.jar and the generated partner.jar are the only libraries needed in the classpath for the code examples
in the following sections.
import java.io.*;
import java.util.*;
import com.sforce.async.*;
import com.sforce.soap.partner.PartnerConnection;
import com.sforce.ws.ConnectionException;
import com.sforce.ws.ConnectorConfig;
87
Sample Client Application Using Java Walk Through the Sample Code
/**
* Creates a Bulk API job and uploads batches for a CSV file.
*/
public void runSample(String sobjectType, String userName,
String password, String sampleFileName)
throws AsyncApiException, ConnectionException, IOException {
BulkConnection connection = getBulkConnection(userName, password);
JobInfo job = createJob(sobjectType, connection);
List<BatchInfo> batchInfoList = createBatchesFromCSVFile(connection, job,
sampleFileName);
closeJob(connection, job.getId());
awaitCompletion(connection, job, batchInfoList);
checkResults(connection, job, batchInfoList);
}
/**
* Create the BulkConnection used to call Bulk API operations.
*/
private BulkConnection getBulkConnection(String userName, String password)
throws ConnectionException, AsyncApiException {
ConnectorConfig partnerConfig = new ConnectorConfig();
partnerConfig.setUsername(userName);
partnerConfig.setPassword(password);
partnerConfig.setAuthEndpoint("https://login.salesforce.com/services/Soap/u/44.0");
88
Sample Client Application Using Java Walk Through the Sample Code
return connection;
}
This BulkConnection instance is the base for using the Bulk API. The instance can be reused for the rest of the application lifespan.
Create a Job
After creating the connection, create a job. Data is always processed in the context of a job. The job specifies the details about the data
being processed: which operation is being executed (insert, update, upsert, or delete) and the object type. The following code creates
a new insert job on the Account object.
/**
* Create a new job using the Bulk API.
*
* @param sobjectType
* The object type being loaded, such as "Account"
* @param connection
* BulkConnection used to create the new job.
* @return The JobInfo for the new job.
* @throws AsyncApiException
*/
private JobInfo createJob(String sobjectType, BulkConnection connection)
throws AsyncApiException {
JobInfo job = new JobInfo();
job.setObject(sobjectType);
job.setOperation(OperationEnum.insert);
job.setContentType(ContentType.CSV);
job = connection.createJob(job);
System.out.println(job);
return job;
}
When a job is created, it’s in the Open state. In this state, new batches can be added to the job. When a job is Closed, batches can
no longer be added.
/**
* Create and upload batches using a CSV file.
* The file into the appropriate size batch files.
*
* @param connection
* Connection to use for creating batches
89
Sample Client Application Using Java Walk Through the Sample Code
* @param jobInfo
* Job associated with new batches
* @param csvFileName
* The source file for batch data
*/
private List<BatchInfo> createBatchesFromCSVFile(BulkConnection connection,
JobInfo jobInfo, String csvFileName)
throws IOException, AsyncApiException {
List<BatchInfo> batchInfos = new ArrayList<BatchInfo>();
BufferedReader rdr = new BufferedReader(
new InputStreamReader(new FileInputStream(csvFileName))
);
// read the CSV header row
byte[] headerBytes = (rdr.readLine() + "\n").getBytes("UTF-8");
int headerBytesLength = headerBytes.length;
File tmpFile = File.createTempFile("bulkAPIInsert", ".csv");
90
Sample Client Application Using Java Walk Through the Sample Code
/**
* Create a batch by uploading the contents of the file.
* This closes the output stream.
*
* @param tmpOut
* The output stream used to write the CSV data for a single batch.
* @param tmpFile
* The file associated with the above stream.
* @param batchInfos
* The batch info for the newly created batch is added to this list.
* @param connection
* The BulkConnection used to create the new batch.
* @param jobInfo
* The JobInfo associated with the new batch.
*/
private void createBatch(FileOutputStream tmpOut, File tmpFile,
List<BatchInfo> batchInfos, BulkConnection connection, JobInfo jobInfo)
throws IOException, AsyncApiException {
tmpOut.flush();
tmpOut.close();
FileInputStream tmpInputStream = new FileInputStream(tmpFile);
try {
BatchInfo batchInfo =
connection.createBatchFromStream(jobInfo, tmpInputStream);
System.out.println(batchInfo);
batchInfos.add(batchInfo);
} finally {
tmpInputStream.close();
}
}
When the server receives a batch, it’s immediately queued for processing. Errors in formatting aren’t reported when sending the batch.
These errors are reported in the result data when the batch is processed.
Tip: To import binary attachments, use the following methods. Specify the CSV, XML, or JSON content for the batch in the
batchContent parameter, or include request.txt in the attached files and pass null to the batchContent
parameter. These methods are contained within the com.async.BulkConnection class:
• createBatchFromDir()
• createBatchWithFileAttachments()
• createBatchWithInputStreamAttachments()
• createBatchFromZipStream()
91
Sample Client Application Using Java Walk Through the Sample Code
job.setId(jobId);
job.setState(JobStateEnum.Closed);
connection.updateJob(job);
}
/**
* Wait for a job to complete by polling the Bulk API.
*
* @param connection
* BulkConnection used to check results.
* @param job
* The job awaiting completion.
* @param batchInfoList
* List of batches for this job.
* @throws AsyncApiException
*/
private void awaitCompletion(BulkConnection connection, JobInfo job,
List<BatchInfo> batchInfoList)
throws AsyncApiException {
long sleepTime = 0L;
Set<String> incomplete = new HashSet<String>();
for (BatchInfo bi : batchInfoList) {
incomplete.add(bi.getId());
}
while (!incomplete.isEmpty()) {
try {
Thread.sleep(sleepTime);
} catch (InterruptedException e) {}
System.out.println("Awaiting results..." + incomplete.size());
sleepTime = 10000L;
BatchInfo[] statusList =
connection.getBatchInfoList(job.getId()).getBatchInfo();
for (BatchInfo b : statusList) {
if (b.getState() == BatchStateEnum.Completed
|| b.getState() == BatchStateEnum.Failed) {
if (incomplete.remove(b.getId())) {
System.out.println("BATCH STATUS:\n" + b);
}
}
}
}
}
A batch is done when it's either failed or completed. This code loops infinitely until all the batches for the job have either failed or
completed.
92
Sample Client Application Using Java Walk Through the Sample Code
/**
* Gets the results of the operation and checks for errors.
*/
private void checkResults(BulkConnection connection, JobInfo job,
List<BatchInfo> batchInfoList)
throws AsyncApiException, IOException {
// batchInfoList was populated when batches were created and submitted
for (BatchInfo b : batchInfoList) {
CSVReader rdr =
new CSVReader(connection.getBatchResultStream(job.getId(), b.getId()));
List<String> resultHeader = rdr.nextRecord();
int resultCols = resultHeader.size();
List<String> row;
while ((row = rdr.nextRecord()) != null) {
Map<String, String> resultInfo = new HashMap<String, String>();
for (int i = 0; i < resultCols; i++) {
resultInfo.put(resultHeader.get(i), row.get(i));
}
boolean success = Boolean.valueOf(resultInfo.get("Success"));
boolean created = Boolean.valueOf(resultInfo.get("Created"));
String id = resultInfo.get("Id");
String error = resultInfo.get("Error");
if (success && created) {
System.out.println("Created row with id " + id);
} else if (!success) {
System.out.println("Failed with error: " + error);
}
}
}
}
This code retrieves the results for each record and reports whether the operation succeeded or failed. If an error occurred for a record,
the code prints out the error.
import java.io.*;
import java.util.*;
import com.sforce.async.*;
import com.sforce.soap.partner.PartnerConnection;
93
Sample Client Application Using Java Walk Through the Sample Code
import com.sforce.ws.ConnectionException;
import com.sforce.ws.ConnectorConfig;
/**
* Creates a Bulk API job and uploads batches for a CSV file.
*/
public void runSample(String sobjectType, String userName,
String password, String sampleFileName)
throws AsyncApiException, ConnectionException, IOException {
BulkConnection connection = getBulkConnection(userName, password);
JobInfo job = createJob(sobjectType, connection);
List<BatchInfo> batchInfoList = createBatchesFromCSVFile(connection, job,
sampleFileName);
closeJob(connection, job.getId());
awaitCompletion(connection, job, batchInfoList);
checkResults(connection, job, batchInfoList);
}
/**
* Gets the results of the operation and checks for errors.
*/
private void checkResults(BulkConnection connection, JobInfo job,
List<BatchInfo> batchInfoList)
throws AsyncApiException, IOException {
// batchInfoList was populated when batches were created and submitted
for (BatchInfo b : batchInfoList) {
CSVReader rdr =
new CSVReader(connection.getBatchResultStream(job.getId(), b.getId()));
List<String> resultHeader = rdr.nextRecord();
int resultCols = resultHeader.size();
List<String> row;
while ((row = rdr.nextRecord()) != null) {
Map<String, String> resultInfo = new HashMap<String, String>();
for (int i = 0; i < resultCols; i++) {
resultInfo.put(resultHeader.get(i), row.get(i));
}
boolean success = Boolean.valueOf(resultInfo.get("Success"));
boolean created = Boolean.valueOf(resultInfo.get("Created"));
94
Sample Client Application Using Java Walk Through the Sample Code
String id = resultInfo.get("Id");
String error = resultInfo.get("Error");
if (success && created) {
System.out.println("Created row with id " + id);
} else if (!success) {
System.out.println("Failed with error: " + error);
}
}
}
}
/**
* Wait for a job to complete by polling the Bulk API.
*
* @param connection
* BulkConnection used to check results.
* @param job
* The job awaiting completion.
* @param batchInfoList
* List of batches for this job.
* @throws AsyncApiException
*/
private void awaitCompletion(BulkConnection connection, JobInfo job,
List<BatchInfo> batchInfoList)
throws AsyncApiException {
long sleepTime = 0L;
Set<String> incomplete = new HashSet<String>();
for (BatchInfo bi : batchInfoList) {
incomplete.add(bi.getId());
}
while (!incomplete.isEmpty()) {
try {
Thread.sleep(sleepTime);
} catch (InterruptedException e) {}
System.out.println("Awaiting results..." + incomplete.size());
sleepTime = 10000L;
BatchInfo[] statusList =
connection.getBatchInfoList(job.getId()).getBatchInfo();
for (BatchInfo b : statusList) {
if (b.getState() == BatchStateEnum.Completed
|| b.getState() == BatchStateEnum.Failed) {
if (incomplete.remove(b.getId())) {
95
Sample Client Application Using Java Walk Through the Sample Code
/**
* Create a new job using the Bulk API.
*
* @param sobjectType
* The object type being loaded, such as "Account"
* @param connection
* BulkConnection used to create the new job.
* @return The JobInfo for the new job.
* @throws AsyncApiException
*/
private JobInfo createJob(String sobjectType, BulkConnection connection)
throws AsyncApiException {
JobInfo job = new JobInfo();
job.setObject(sobjectType);
job.setOperation(OperationEnum.insert);
job.setContentType(ContentType.CSV);
job = connection.createJob(job);
System.out.println(job);
return job;
}
/**
* Create the BulkConnection used to call Bulk API operations.
*/
private BulkConnection getBulkConnection(String userName, String password)
throws ConnectionException, AsyncApiException {
ConnectorConfig partnerConfig = new ConnectorConfig();
partnerConfig.setUsername(userName);
partnerConfig.setPassword(password);
partnerConfig.setAuthEndpoint("https://login.salesforce.com/services/Soap/u/44.0");
96
Sample Client Application Using Java Walk Through the Sample Code
/**
* Create and upload batches using a CSV file.
* The file into the appropriate size batch files.
*
* @param connection
* Connection to use for creating batches
* @param jobInfo
* Job associated with new batches
* @param csvFileName
* The source file for batch data
*/
private List<BatchInfo> createBatchesFromCSVFile(BulkConnection connection,
JobInfo jobInfo, String csvFileName)
throws IOException, AsyncApiException {
List<BatchInfo> batchInfos = new ArrayList<BatchInfo>();
BufferedReader rdr = new BufferedReader(
new InputStreamReader(new FileInputStream(csvFileName))
);
// read the CSV header row
byte[] headerBytes = (rdr.readLine() + "\n").getBytes("UTF-8");
int headerBytesLength = headerBytes.length;
File tmpFile = File.createTempFile("bulkAPIInsert", ".csv");
97
Sample Client Application Using Java Walk Through the Sample Code
if (currentBytes == 0) {
tmpOut = new FileOutputStream(tmpFile);
tmpOut.write(headerBytes);
currentBytes = headerBytesLength;
currentLines = 1;
}
tmpOut.write(bytes);
currentBytes += bytes.length;
currentLines++;
}
// Finished processing all rows
// Create a final batch for any remaining data
if (currentLines > 1) {
createBatch(tmpOut, tmpFile, batchInfos, connection, jobInfo);
}
} finally {
tmpFile.delete();
}
return batchInfos;
}
/**
* Create a batch by uploading the contents of the file.
* This closes the output stream.
*
* @param tmpOut
* The output stream used to write the CSV data for a single batch.
* @param tmpFile
* The file associated with the above stream.
* @param batchInfos
* The batch info for the newly created batch is added to this list.
* @param connection
* The BulkConnection used to create the new batch.
* @param jobInfo
* The JobInfo associated with the new batch.
*/
private void createBatch(FileOutputStream tmpOut, File tmpFile,
List<BatchInfo> batchInfos, BulkConnection connection, JobInfo jobInfo)
throws IOException, AsyncApiException {
tmpOut.flush();
tmpOut.close();
FileInputStream tmpInputStream = new FileInputStream(tmpFile);
try {
BatchInfo batchInfo =
connection.createBatchFromStream(jobInfo, tmpInputStream);
System.out.println(batchInfo);
batchInfos.add(batchInfo);
} finally {
tmpInputStream.close();
}
}
98
Sample Client Application Using Java Walk Through the Sample Code
99
APPENDIX B Map Data Fields
To use Bulk API to import data that was exported directly from Microsoft Outlook, Google Contacts, and other third-party sources, map
data fields in any CSV import file to Salesforce data fields. The CSV import file does not need to be Bulk API–compatible.
For example, you might have a CSV import file that includes a field called Number that you want to map to the standard Salesforce
field AccountNumber. When you add a batch job using Bulk API, data from your Number field is imported into (or updates) the
AccountNumber field in Salesforce.
To add a batch job that maps data fields to Salesforce data fields:
1. Create a transformation spec (spec.csv) that defines data field mappings. (This is different from the CSV import file that contains your
data.)
2. Create a new job that specifies an object and action, just as you would for any other Bulk API job.
3. Upload the transformation spec.
4. Send data to the server in batches.
Field Description
Salesforce Field The Salesforce field you want to map to.
Csv Header The field in your import file you want to map.
Hint Tells Bulk API how to interpret data in the import file.
Bulk API can use this value to do two things:
• Interpret Java format strings for date and time fields
• Define what is true using regular expressions for boolean fields
100
Map Data Fields
Field Description
This field is optional.
Considerations
• Transformation specs must be CSV files. XML and JSON files are not supported.
• Transformation specs (spec.csv files) must use UTF-8 encoding. CSV import files do not need to use UTF-8 encoding. (You can specify
the encoding in the Content-Type header.)
• Transformation specs are not persistent; their scopes are limited to the current job.
101
GLOSSARY
A |B |C |D |E |F |G |H |I |J |K |L |M |N |O |P |Q |R |S |T |U |V |W |X |Y |Z
A
Apex
Apex is a strongly typed, object-oriented programming language that allows developers to execute flow and transaction control
statements on the Lightning platform server in conjunction with calls to the Lightning Platform API. Using syntax that looks like Java
and acts like database stored procedures, Apex enables developers to add business logic to most system events, including button
clicks, related record updates, and Visualforce pages. Apex code can be initiated by Web service requests and from triggers on objects.
App
Short for “application.” A collection of components such as tabs, reports, dashboards, and Visualforce pages that address a specific
business need. Salesforce provides standard apps such as Sales and Service. You can customize the standard apps to match the way
you work. In addition, you can package an app and upload it to the AppExchange along with related components such as custom
fields, custom tabs, and custom objects. Then, you can make the app available to other Salesforce users from the AppExchange.
Application Programming Interface (API)
The interface that a computer system, library, or application provides to allow other computer programs to request services from it
and exchange data.
Asynchronous Calls
A call that doesn’t return results immediately because the operation can take a long time. Calls in the Metadata API and Bulk API are
asynchronous.
B
Batch, Bulk API
A batch is a CSV, XML, or JSON representation of a set of records in the Bulk API.You can process a set of records by creating a job
that contains one or more batches. The server processes each batch independently, not necessarily in the order it is received. See
Job, Bulk API.
Boolean Operators
You can use Boolean operators in report filters to specify the logical relationship between two values. For example, the AND operator
between two values yields search results that include both values. Likewise, the OR operator between two values yields search results
that include either value.
Bulk API
The REST-based Bulk API is optimized for processing large sets of data. It allows you to query, insert, update, upsert, or delete a large
number of records asynchronously by submitting a number of batches which are processed in the background by Salesforce. See
also SOAP API.
102
Glossary
C
Client App
An app that runs outside the Salesforce user interface and uses only the Lightning Platform API or Bulk API. It typically runs on a
desktop or mobile device. These apps treat the platform as a data source, using the development model of whatever tool and
platform for which they are designed.
CSV (Comma Separated Values)
A file format that enables the sharing and transportation of structured data. The import wizards, Data Loader and the Bulk API support
CSV. Each line in a CSV file represents a record. A comma separates each field value in the record.
Custom Field
A field that can be added in addition to the standard fields to customize Salesforce for your organization’s needs.
Custom Object
Custom records that allow you to store information unique to your organization.
D
Data Loader
A Lightning Platform tool used to import and export data from your Salesforce organization.
Database
An organized collection of information. The underlying architecture of the Lightning Platform includes a database where your data
is stored.
Database Table
A list of information, presented with rows and columns, about the person, thing, or concept you want to track. See also Object.
Decimal Places
Parameter for number, currency, and percent custom fields that indicates the total number of digits you can enter to the right of a
decimal point, for example, 4.98 for an entry of 2. Note that the system rounds the decimal numbers you enter, if necessary. For
example, if you enter 4.986 in a field with Decimal Places of 2, the number rounds to 4.99. Salesforce uses the round half-up
rounding algorithm. Half-way values are always rounded up. For example, 1.45 is rounded to 1.5. –1.45 is rounded to –1.5.
Dependent Field
Any custom picklist or multi-select picklist field that displays available values based on the value selected in its corresponding
controlling field.
Developer Edition
A free, fully-functional Salesforce organization designed for developers to extend, integrate, and develop with the Lightning Platform.
Developer Edition accounts are available on developer.salesforce.com.
Salesforce Developers
The Salesforce Developers website at developer.salesforce.com provides a full range of resources for platform developers, including
sample code, toolkits, an online developer community, and the ability to obtain limited Lightning Platform environments.
E
Enterprise Edition
A Salesforce edition designed for larger, more complex businesses.
103
Glossary
F
Field
A part of an object that holds a specific piece of information, such as a text or currency value.
Field-Level Security
Settings that determine whether fields are hidden, visible, read only, or editable for users. Available in Professional, Enterprise,
Unlimited, Performance, and Developer Editions.
Lightning Platform
The Salesforce platform for building applications in the cloud. Lightning Platform combines a powerful user interface, operating
system, and database to allow you to customize and deploy applications in the cloud for your entire enterprise.
Force.com IDE
An Eclipse plug-in that allows developers to manage, author, debug and deploy Lightning Platform applications in the Eclipse
development environment.
Ant Migration Tool
A toolkit that allows you to write an Apache Ant build script for migrating Lightning Platform components between a local file system
and a Salesforce organization.
Foreign Key
A field whose value is the same as the primary key of another table. You can think of a foreign key as a copy of a primary key from
another table. A relationship is made between two tables by matching the values of the foreign key in one table with the values of
the primary key in another.
Formula Field
A type of custom field. Formula fields automatically calculate their values based on the values of merge fields, expressions, or other
values.
Function
Built-in formulas that you can customize with input parameters. For example, the DATE function creates a date field type from a
given year, month, and day.
G
Gregorian Year
A calendar based on a 12-month structure used throughout much of the world.
H
No Glossary items for this entry.
I
ID
See Salesforce Record ID.
Instance
The cluster of software and hardware represented as a single logical server that hosts an organization's data and runs their applications.
The Lightning Platform runs on multiple instances, but data for any single organization is always stored on a single instance.
104
Glossary
Integration User
A Salesforce user defined solely for client apps or integrations. Also referred to as the logged-in user in a SOAP API context.
ISO Code
The International Organization for Standardization country code, which represents each country by two letters.
J
Job, Bulk API
A job in the Bulk API specifies which object is being processed (for example, Account, Opportunity) and what type of action is being
used (insert, upsert, update, or delete). You process a set of records by creating a job that contains one or more batches. See Batch,
Bulk API.
JSON (JavsScript Object Notation)
JSON is a lightweight format for transferring data.
K
No Glossary items for this entry.
L
Locale
The country or geographic region in which the user is located. The setting affects the format of date and number fields, for example,
dates in the English (United States) locale display as 06/30/2000 and as 30/06/2000 in the English (United Kingdom) locale.
In Professional, Enterprise, Unlimited, Performance, and Developer Edition organizations, a user’s individual Locale setting overrides
the organization’s Default Locale setting. In Personal and Group Editions, the organization-level locale field is called Locale,
not Default Locale.
Logged-in User
In a SOAP API context, the username used to log into Salesforce. Client applications run with the permissions and sharing of the
logged-in user. Also referred to as an integration user.
Lookup Field
A type of field that contains a linkable value to another record. You can display lookup fields on page layouts where the object has
a lookup or master-detail relationship with another object. For example, cases have a lookup relationship with assets that allows
users to select an asset using a lookup dialog from the case edit page and click the name of the asset from the case detail page.
M
Managed Package
A collection of application components that is posted as a unit on the AppExchange and associated with a namespace and possibly
a License Management Organization. To support upgrades, a package must be managed. An organization can create a single
managed package that can be downloaded and installed by many different organizations. Managed packages differ from unmanaged
packages by having some locked components, allowing the managed package to be upgraded later. Unmanaged packages do not
include locked components and cannot be upgraded. In addition, managed packages obfuscate certain components (like Apex) on
subscribing organizations to protect the intellectual property of the developer.
105
Glossary
Manual Sharing
Record-level access rules that allow record owners to give read and edit permissions to other users who might not have access to
the record any other way.
Many-to-Many Relationship
A relationship where each side of the relationship can have many children on the other side. Many-to-many relationships are
implemented through the use of junction objects.
Master-Detail Relationship
A relationship between two different types of records that associates the records with each other. For example, accounts have a
master-detail relationship with opportunities. This type of relationship affects record deletion, security, and makes the lookup
relationship field required on the page layout.
Metadata
Information about the structure, appearance, and functionality of an organization and any of its parts. Lightning Platform uses XML
to describe metadata.
Multitenancy
An application model where all users and apps share a single, common infrastructure and code base.
N
Native App
An app that is built exclusively with setup (metadata) configuration on Lightning Platform. Native apps do not require any external
services or infrastructure.
O
Object
An object allows you to store information in your Salesforce organization. The object is the overall definition of the type of information
you are storing. For example, the case object allow you to store information regarding customer inquiries. For each object, your
organization will have multiple records that store the information about specific instances of that type of data. For example, you
might have a case record to store the information about Joe Smith's training inquiry and another case record to store the information
about Mary Johnson's configuration issue.
Object-Level Security
Settings that allow an administrator to hide whole objects from users so that they don't know that type of data exists. Object-level
security is specified with object permissions.
One-to-Many Relationship
A relationship in which a single object is related to many other objects. For example, an account may have one or more related
contacts.
Organization-Wide Defaults
Settings that allow you to specify the baseline level of data access that a user has in your organization. For example, you can set
organization-wide defaults so that any user can see any record of a particular object that is enabled via their object permissions, but
they need extra permissions to edit one.
Outbound Message
An outbound message sends information to a designated endpoint, like an external service. Outbound messages are configured
from Setup. You must configure the external endpoint and create a listener for the messages using the SOAP API.
106
Glossary
Owner
Individual user to which a record (for example, a contact or case) is assigned.
P
Package
A group of Lightning Platform components and applications that are made available to other organizations through the AppExchange.
You use packages to bundle an app along with any related components so that you can upload them to AppExchange together.
Parent Account
An organization or company that an account is affiliated. By specifying a parent for an account, you can get a global view of all
parent/subsidiary relationships using the View Hierarchy link.
Picklist
Selection list of options available for specific fields in a Salesforce object, for example, the Industry field for accounts. Users can
choose a single value from a list of options rather than make an entry directly in the field. See also Master Picklist.
Picklist (Multi-Select)
Selection list of options available for specific fields in a Salesforce object. Multi-select picklists allow users to choose one or more
values. Users can choose a value by double clicking on it, or choose additional values from a scrolling list by holding down the CTRL
key while clicking a value and using the arrow icon to move them to the selected box.
Picklist Values
Selections displayed in drop-down lists for particular fields. Some values come predefined, and other values can be changed or
defined by an administrator.
Platform Edition
A Salesforce edition based on Enterprise, Unlimited, or Performance Edition that does not include any of the standard Salesforce
apps, such as Sales or Service & Support.
Primary Key
A relational database concept. Each table in a relational database has a field in which the data value uniquely identifies the record.
This field is called the primary key. The relationship is made between two tables by matching the values of the foreign key in one
table with the values of the primary key in another.
Production Organization
A Salesforce organization that has live users accessing data.
Professional Edition
A Salesforce edition designed for businesses who need full-featured CRM functionality.
Q
Query String Parameter
A name-value pair that's included in a URL, typically after a '?' character. For example:
https://yourInstance.salesforce.com/001/e?name=value
R
Record
A single instance of a Salesforce object. For example, “John Jones” might be the name of a contact record.
107
Glossary
Record Name
A standard field on all Salesforce objects. Whenever a record name is displayed in a Lightning Platform application, the value is
represented as a link to a detail view of the record. A record name can be either free-form text or an autonumber field. Record
Name does not have to be a unique value.
Record Type
A record type is a field available for certain records that can include some or all of the standard and custom picklist values for that
record. You can associate record types with profiles to make only the included picklist values available to users with that profile.
Record-Level Security
A method of controlling data in which you can allow a particular user to view and edit an object, but then restrict the records that
the user is allowed to see.
Recycle Bin
A page that lets you view and restore deleted information. Access the Recycle Bin by using the link in the sidebar.
Related Object
Objects chosen by an administrator to display in the Agent console's mini view when records of a particular type are shown in the
console's detail view. For example, when a case is in the detail view, an administrator can choose to display an associated account,
contact, or asset in the mini view.
Relationship
A connection between two objects, used to create related lists in page layouts and detail levels in reports. Matching values in a
specified field in both objects are used to link related data; for example, if one object stores data about companies and another
object stores data about people, a relationship allows you to find out which people work at the company.
Relationship Query
In a SOQL context, a query that traverses the relationships between objects to identify and return results. Parent-to-child and
child-to-parent syntax differs in SOQL queries.
Role Hierarchy
A record-level security setting that defines different levels of users such that users at higher levels can view and edit information
owned by or shared with users beneath them in the role hierarchy, regardless of the organization-wide sharing model settings.
Roll-Up Summary Field
A field type that automatically provides aggregate values from child records in a master-detail relationship.
Running User
Each dashboard has a running user, whose security settings determine which data to display in a dashboard. If the running user is a
specific user, all dashboard viewers see data based on the security settings of that user—regardless of their own personal security
settings. For dynamic dashboards, you can set the running user to be the logged-in user, so that each user sees the dashboard
according to his or her own access level.
S
SaaS
See Software as a Service (SaaS).
Salesforce Record ID
A unique 15- or 18-character alphanumeric string that identifies a single record in Salesforce.
Salesforce SOA (Service-Oriented Architecture)
A powerful capability of Lightning Platform that allows you to make calls to external Web services from within Apex.
108
Glossary
Sandbox
A nearly identical copy of a Salesforce production organization for development, testing, and training. The content and size of a
sandbox varies depending on the type of sandbox and the edition of the production organization associated with the sandbox.
Session ID
An authentication token that is returned when a user successfully logs in to Salesforce. The Session ID prevents a user from having
to log in again every time they want to perform another action in Salesforce. Different from a record ID or Salesforce ID, which are
terms for the unique ID of a Salesforce record.
Session Timeout
The time after login before a user is automatically logged out. Sessions expire automatically after a predetermined length of inactivity,
which can be configured in Salesforce from Setup by clicking Security Controls. The default is 120 minutes (two hours). The inactivity
timer is reset to zero if a user takes an action in the web interface or makes an API call.
Setup
A menu where administrators can customize and define organization settings and Lightning Platform apps. Depending on your
organization’s user interface settings, Setup may be a link in the user interface header or in the dropdown list under your name.
Sharing
Allowing other users to view or edit information you own. There are different ways to share data:
• Sharing Model—defines the default organization-wide access levels that users have to each other’s information and whether
to use the hierarchies when determining access to data.
• Role Hierarchy—defines different levels of users such that users at higher levels can view and edit information owned by or
shared with users beneath them in the role hierarchy, regardless of the organization-wide sharing model settings.
• Sharing Rules—allow an administrator to specify that all information created by users within a given group or role is automatically
shared to the members of another group or role.
• Manual Sharing—allows individual users to share records with other users or groups.
• Apex-Managed Sharing—enables developers to programmatically manipulate sharing to support their application’s behavior.
See Apex-Managed Sharing.
Sharing Model
Behavior defined by your administrator that determines default access by users to different types of records.
Sharing Rule
Type of default sharing created by administrators. Allows users in a specified group or role to have access to all information created
by users within a given group or role.
SOAP (Simple Object Access Protocol)
A protocol that defines a uniform way of passing XML-encoded data.
Software as a Service (SaaS)
A delivery model where a software application is hosted as a service and provided to customers via the Internet. The SaaS vendor
takes responsibility for the daily maintenance, operation, and support of the application and each customer's data. The service
alleviates the need for customers to install, configure, and maintain applications with their own hardware, software, and related IT
resources. Services can be delivered using the SaaS model to any market segment.
SOQL (Salesforce Object Query Language)
A query language that allows you to construct simple but powerful query strings and to specify the criteria that selects data from
the Lightning Platform database.
SOSL (Salesforce Object Search Language)
A query language that allows you to perform text-based searches using the Lightning Platform API.
109
Glossary
Standard Object
A built-in object included with the Lightning Platform. You can also build custom objects to store information that is unique to your
app.
T
Translation Workbench
The Translation Workbench lets you specify languages you want to translate, assign translators to languages, create translations for
customizations you’ve made to your Salesforce organization, and override labels and translations from managed packages. Everything
from custom picklist values to custom fields can be translated so your global users can use Salesforce in their language.
U
Unlimited Edition
Unlimited Edition is Salesforce’s solution for maximizing your success and extending that success across the entire enterprise through
the Lightning Platform.
Unmanaged Package
A package that cannot be upgraded or controlled by its developer.
V
Visualforce
A simple, tag-based markup language that allows developers to easily define custom pages and components for apps built on the
platform. Each tag corresponds to a coarse or fine-grained component, such as a section of a page, a related list, or a field. The
components can either be controlled by the same logic that is used in standard Salesforce pages, or developers can associate their
own logic with a controller written in Apex.
W
Web Service
A mechanism by which two applications can easily exchange data over the Internet, even if they run on different platforms, are
written in different languages, or are geographically remote from each other.
Web Services API
A Web services application programming interface that provides access to your Salesforce organization's information. See also SOAP
PI and Bulk API.
WSDL (Web Services Description Language) File
An XML file that describes the format of messages you send and receive from a Web service. Your development environment's SOAP
client uses the Salesforce Enterprise WSDL or Partner WSDL to communicate with Salesforce using the SOAP API.
110
Glossary
X
XML (Extensible Markup Language)
A markup language that enables the sharing and transportation of structured data. All Lightning Platform components that are
retrieved or deployed through the Metadata API are represented by XML definitions.
Y
No Glossary items for this entry.
Z
No Glossary items for this entry.
111
INDEX
A E
Abort job 38 Errors
Add batch 8, 42 batch results 51
B G
Batch lifespan 40 Get job details 37
Batch Retry header 79 Get job status and results 37
Batches Guidelines
add to a job 8, 42 Compression in responses 14
check status 10
create 42 H
get a request 48 Headers
get information 44 Batch Retry 79
get information for job 45 Content Type 78
handle failed rows 51 Line Ending 79
interpret state 47 PK Chunking 80
retrieve results 10
Binary attachments J
batch file 26 Job lifespan 40
create a batch 28 Jobs
create a job 27 abort 38
manifest file 26 close 9, 35
zip file 27 create 7, 33
Bulk Query 53–54 gett details 37
JSON
C null values 23
Checking batch status 10 records 23
Close job 9, 35 sample file 24
Code sample JSON data files 19
walk through sample code 59, 64
Content Type header 78 L
Create batch 8, 42 Line Ending header 79
Create job 7, 33 Lock contention 13
CSV Logging in 31
sample file 19 Longevity of jobs and batches 40
D O
Data files Operations
date format 16 on jobs 32
JSON 19
XML 19 P
Date format 16 PK Chunking header 80
Polymorphic field 19
112
Index
Session header 31
Q State
Quick start
interpret for batch 47
cURL 5
Status
set up your client 5
get for batch 44
get for batches 45
R get for job 37
Reference interpret for batch 47
batches (BatchInfo) 76
Request X
get for batch 48
XML
Response compression 14
null values 23
Results
polymorphic field 19
handle failed rows 51
records 23
Retrieving batch results 10
relationship field 19
sample file 23
S XML data files 19
Sample job operations 32
113
Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.
Alternative Proxies: