

SalesforceBulk Connector Reference¶

The following operations allow you to work with the Salesforce Bulk Connector. Click an operation name to see parameter details and samples on how to use it.

Initialize the connector¶

Salesforce Bulk API uses the OAuth protocol to allow application users to securely access data without having to reveal their user credentials. For more information on how authentication is done in Salesforce, see Understanding Authentication. You can provide only access token and use it until it expires. After expiry, you will be responsible for getting a new access token and using it. Alternatively, you have the option of providing refresh token, client secret, and client ID which will be used to get access token initially and after every expiry by the connector itself. You will not be required to handle access token expiry in this case.

To use the Salesforce Bulk connector, add the <salesforcebulk.init> element in your configuration before carrying out any other Salesforce Bulk operations.

salesforcebulk.init

The salesforcebulk.init operation initializes the connector to interact with the Salesforce Bulk API. See the related API documentation for more information.

Parameter Name	Description	Required
apiVersion	The version of the Salesforce API.	Yes
accessToken	The access token to authenticate your API calls.	No
apiUrl	The instance URL for your organization.	Yes
tokenEndpointHostname	The instance url for OAuth 2.0 token endpoint when issuing authentication requests in your application. If you haven't set any token endpoint hostname, the default hostname https://login.salesforce.com will be set.	No
refreshToken	The refresh token that you received to refresh the API access token.	No
clientId	The consumer key of the connected application that you created.	No
clientSecret	The consumer secret of the connected application that you created.	No

Sample configuration

<salesforcebulk.init>
    <apiVersion>{$ctx:apiVersion}</apiVersion>
    <accessToken>{$ctx:accessToken}</accessToken>
    <apiUrl>{$ctx:apiUrl}</apiUrl>
    <tokenEndpointHostname>{$ctx:tokenEndpointHostname}</tokenEndpointHostname>
</salesforcebulk.init>

Sample request

<salesforcebulk.init>
    <apiVersion>34.0</apiVersion>
    <accessToken>XXXXXXXXXXXX (Replace with your access token)</accessToken>
    <apiUrl>https://ap17.salesforce.com</apiUrl>
    <tokenEndpointHostname>{$ctx:tokenEndpointHostname}</tokenEndpointHostname>
</salesforcebulk.init>

Or if you want the connector to handle token expiry

Sample configuration

<salesforcebulk.init>
    <apiVersion>{$ctx:apiVersion}</apiVersion>
    <apiUrl>{$ctx:apiUrl}</apiUrl>
    <tokenEndpointHostname>{$ctx:tokenEndpointHostname}</tokenEndpointHostname>
    <refreshToken>{$ctx:refreshToken}</refreshToken>
    <clientId>{$ctx:clientId}</clientId>
    <clientSecret>{$ctx:clientSecret}</clientSecret>
</salesforcebulk.init>

Sample request

<salesforcebulk.init>
    <apiVersion>34.0</apiVersion>
    <apiUrl>https://ap17.salesforce.com</apiUrl>
    <tokenEndpointHostname>{$ctx:tokenEndpointHostname}</tokenEndpointHostname>
    <refreshToken>XXXXXXXXXXXX (Replace with your refresh token)</refreshToken>
    <clientId>XXXXXXXXXXXX (Replace with your client ID)</clientId>
    <clientSecret>XXXXXXXXXXXX (Replace with your client secret)</clientSecret>
</salesforcebulk.init>

Working with Jobs¶

createJob

The salesforcebulk.createJob method creates a new job based on the properties that you specify. See the related API documentation for more information.

Parameter Name	Description	Required
operation	The processing operation that the job should perform.	Yes
contentType	The content type of the job.	Yes
object	The object type of data that is to be processed by the job.	Yes
externalIdFieldName	The id of the external object.	No

Sample configuration

Following is a sample request that can be handled by the createJob operation.

<salesforcebulk.createJob>
    <operation>{$ctx:operation}</operation>
    <contentType>{$ctx:contentType}</contentType>
    <object>{$ctx:object}</object>
    <externalIdFieldName>{$ctx:externalIdFieldName}</externalIdFieldName>
</salesforcebulk.createJob>

Sample request

<createJob>
   <apiVersion>34.0</apiVersion>
   <accessToken>XXXXXXXXXXXX (Replace with your access token)</accessToken>
   <apiUrl>https://(your_instance).salesforce.com</apiUrl>
   <operation>insert</operation>
   <contentType>CSV</contentType>
   <object>Contact</object>
   <externalIdFieldName>Languages__c</externalIdFieldName>
</createJob>

updateJob

The salesforcebulk.updateJob method closes or aborts a job that you specify. See the related API documentation for more information.

Parameter Name	Description	Required
jobId	The ID of the job that you either want to close or abort.	Yes
state	The state of processing of the job.	Yes

Sample configuration

Following is a sample request that can be handled by the updateJob operation.

<salesforcebulk.updateJob>
    <jobId>{$ctx:jobId}</jobId>
    <state>{$ctx:state}</state>
</salesforcebulk.updateJob>

Sample request

<updateJob>
   <apiVersion>34.0</apiVersion>
   <accessToken>XXXXXXXXXXXX (Replace with your access token)</accessToken>
   <apiUrl>https://(your_instance).salesforce.com</apiUrl>
   <jobId>75028000000MCtIAAW</jobId>
   <state>Closed</state>
</updateJob>

getJob

The salesforcebulk.getJob method retrieves all details of an existing job based on the job ID that you specify. See the related API documentation for more information.

Parameter Name	Description	Required
jobId	The ID of the job that you either want to close or abort.	Yes

Sample configuration

Following is a sample request that can be handled by the getJob operation.

<salesforcebulk.getJob>
    <jobId>{$ctx:jobId}</jobId>
</salesforcebulk.getJob>

Sample request

<getJob>
   <apiVersion>34.0</apiVersion>
   <accessToken>XXXXXXXXXXXX (Replace with your access token)</accessToken>
   <apiUrl>https://(your_instance).salesforce.com</apiUrl>
   <jobId>75028000000MCqEAAW</jobId>
</getJob>

Working with Batches¶

addBatch

The salesforcebulk.addBatch method adds a new batch to a job based on the properties that you specify. See the related API documentation for more information.

Parameter Name	Description	Required
jobId	The ID of the job that you either want to close or abort.	Yes
objects	A list of records to process.	Yes
contentType	The content type of the batch data. The content type you specify should be compatible with the content type of the associated job. Possible values are application/xml and text/csv.	Yes
isQuery	Set to true if the operation is query.	Yes

Sample configuration

<salesforcebulk.addBatch>
    <jobId>{$ctx:jobId}</jobId>
    <objects>{$ctx:objects}</objects>
    <contentType>{$ctx:contentType}</contentType>
    <isQuery>{$ctx:isQuery}</isQuery>
</salesforcebulk.addBatch>

Sample request

Following is a sample request that can be handled by the addBatch operation, where the content type of the batch data is in application/xml format.

<addBatch>
   <apiUrl>https://(your_instance).salesforce.com</apiUrl>
   <apiVersion>34.0</apiVersion>
   <accessToken>XXXXXXXXXXXX (Replace with your access token)</accessToken>
   <contentType>application/xml</contentType>
   <isQuery>false</isQuery>
   <jobId>75028000000McSwAAK</jobId>
   <objects>
      <values>
         <sObject>
            <description>Created from Bulk API on Tue Apr 14 11:15:59 PDT 2009</description>
            <name>Account 711 (batch 0)</name>
         </sObject>
         <sObject>
            <description>Created from Bulk API on Tue Apr 14 11:15:59 PDT 2009</description>
            <name>Account 37811 (batch 5)</name>
         </sObject>
      </values>
   </objects>
</addBatch>

Following is a sample request that can be handled by the addBatch operation, where the content type of the batch data is in text/csv format.

<addBatch>
   <apiUrl>https://(your_instance).salesforce.com</apiUrl>
   <apiVersion>34.0</apiVersion>
   <accessToken>XXXXXXXXXXXX (Replace with your access token)</accessToken>
   <contentType>text/csv</contentType>
   <isQuery>false</isQuery>
   <jobId>75028000000McSwAAK</jobId>
   <objects>
      <values>Name,description
        Tom Dameon,Created from Bulk API
      </values>
   </objects>
</addBatch>

Following is a sample request that can be handled by the addBatch operation, where the operation is query and the content type of the bulk query results is in application/xml format.

<addBatch>
   <apiUrl>https://(your_instance).salesforce.com</apiUrl>
   <apiVersion>34.0</apiVersion>
   <accessToken>XXXXXXXXXXXX (Replace with your access token)</accessToken>
   <contentType>application/xml</contentType>
   <isQuery>true</isQuery>
   <jobId>75028000000McSwAAK</jobId>
   <objects>
      <values>SELECT Id, Name FROM Account LIMIT 100</values>
   </objects>
</addBatch>

getBatchStatus

The salesforcebulk.getBatchStatus method retrieves the status of a batch based on the properties that you specify. See the related API documentation for more information.

Parameter Name	Description	Required
jobId	The unique identifier of the job to which the batch you specify belongs.	Yes
batchId	The unique identifier of the batch for which you want to retrieve the status.	Yes

Sample configuration

Following is a sample request that can be handled by the getBatchStatus operation.

<salesforcebulk.getBatchStatus>
    <jobId>{$ctx:jobId}</jobId>
    <batchId>{$ctx:batchId}</batchId>   
</salesforcebulk.getBatchStatus>

Sample request

<getBatchStatus>
    <apiUrl>https://(your_instance).salesforce.com</apiUrl>
    <accessToken>XXXXXXXXXXXX (Replace with your access token)</accessToken>
    <apiVersion>34.0</apiVersion>
    <jobId>75028000000M5X0</jobId>
    <batchId>75128000000OZzq</batchId>
</getBatchStatus>

getBatchResults

The salesforcebulk.getBatchResults method retrieves results of a batch that has completed processing. See the related API documentation for more information.

Parameter Name	Description	Required
jobId	The unique identifier of the job to which the batch you specify belongs.	Yes
batchId	The unique identifier of the batch for which you want to retrieve results.	Yes

Sample configuration

Following is a sample request that can be handled by the getBatchResults operation.

<salesforcebulk.getBatchRequest>
    <jobId>{$ctx:jobId}</jobId>
    <batchId>{$ctx:batchId}</batchId>
</salesforcebulk.getBatchRequest>

Sample request

<getBatchResults>
   <apiUrl>https://(your_instance).salesforce.com</apiUrl>
   <apiVersion>34.0</apiVersion>
   <accessToken>XXXXXXXXXXXX (Replace with your access token)</accessToken>
   <jobId>75028000000M5X0</jobId>
   <batchId>75128000000OZzq</batchId>
</getBatchResults>

getBatchRequest

The salesforcebulk.getBatchRequest method retrieves a batch request based on the properties that you specify. See the related API documentation for more information.

Parameter Name	Description	Required
jobId	The unique identifier of the job to which the batch you specify belongs.	Yes
batchId	The unique identifier of the batch for which you want to retrieve the batch request.	Yes

Sample configuration

Following is a sample request that can be handled by the getBatchRequest operation.

<salesforcebulk.getBatchRequest>
    <jobId>{$ctx:jobId}</jobId>
    <batchId>{$ctx:batchId}</batchId>
</salesforcebulk.getBatchRequest>

Sample request

<getBatchRequest>
   <apiVersion>34.0</apiVersion>
   <accessToken>XXXXXXXXXXXX (Replace with your access token)</accessToken>
   <apiUrl>https://(your_instance).salesforce.com</apiUrl>
   <jobId>75028000000MCtIAAW</jobId>
   <batchId>75128000000OpZFAA0</batchId>
</getBatchRequest>

listBatches

The salesforcebulk.listBatches method retrieves details of all batches in a job that you specify. See the related API documentation for more information.

Parameter Name	Description	Required
jobId	The unique identifier of the job for which you want to retrieve batch details.	Yes

Sample configuration

Following is a sample request that can be handled by the listBatches operation.

<salesforcebulk.listBatches>
    <jobId>{$ctx:jobId}</jobId>
</salesforcebulk.listBatches>

Sample request

<listBatches>
   <apiVersion>34.0</apiVersion>
   <accessToken>XXXXXXXXXXXX (Replace with your access token)</accessToken>
   <apiUrl>https://(your_instance).salesforce.com</apiUrl>
   <jobId>75028000000MCqEAAW</jobId>
</listBatches>

getBulkQueryResults

The salesforcebulk.getBulkQueryResults method retrieves the bulk query results that you specify. See the related API documentation for more information.

Parameter Name	Description	Required
jobId	The unique identifier of the job for which you want to retrieve batch details.	Yes
batchId	The unique identifier of the batch for which you want to retrieve the batch request.	Yes
resultId	The unique identifier of the results for which you want to retrieve.	Yes

Sample configuration

Following is a sample request that can be handled by the getBulkQueryResults operation.

<salesforcebulk.getBulkQueryResults>
    <jobId>{$ctx:jobId}</jobId>
    <batchId>{$ctx:batchId}</batchId>
    <resultId>{$ctx:resultId}</resultId>
</salesforcebulk.getBulkQueryResults>

Sample request

<getBulkQueryResults>
   <apiVersion>34.0</apiVersion>
   <accessToken>XXXXXXXXXXXX (Replace with your access token)</accessToken>
   <apiUrl>https://(your_instance).salesforce.com</apiUrl>
   <jobId>75028000000MCqEAAW</jobId>
   <batchId>7510K00000Kzb6XQAR</batchId>
   <resultId>7520K000006xofz</resultId>
</getBulkQueryResults>

Working with Binary Attachments¶

createJobToUploadBatchFile

The salesforcebulk.createJobToUploadBatchFile method creates a job for batches that contain attachment records. See the related API documentation for more information.

Sample configuration

Following is a sample request that can be handled by the createJobToUploadBatchFile operation. It creates a job for batches that contain attachment records..

<salesforcebulk.createJobToUploadBatchFile>
</salesforcebulk.createJobToUploadBatchFile>

Sample request

http://localhost:8280/services/salesforcebulk_uploadBatchFile?apiUrl=https://(your_instance).salesforce.com&accessToken=XXXXXXXXXXXXXXXXX&apiVersion=34.0&refreshToken=XXXXXXXXXXXXXXXXX&clientId=XXXXXXXXXXXXXXXXX&clientSecret=XXXXXXXXXXXXXXXXX&jobId=75028000000MCv9AAG

getBulkQueryResults

The salesforcebulk.getBulkQueryResults method creates a batch of attachment records. See the related API documentation for more information.

Parameter Name	Description	Required
jobId	The ID of the job for which you want to create a batch of attachment records.	Yes

Sample configuration

Following is a sample request that can be handled by the uploadBatchFile operation.It creates a job for batches that contain attachment records.

<salesforcebulk.uploadBatchFile>
   <jobId>{$url:jobId}</jobId>
</salesforcebulk.uploadBatchFile>

Sample request

http://localhost:8280/services/salesforcebulk_uploadBatchFile?apiUrl=https://(your_instance).salesforce.com&accessToken=XXXXXXXXXXXXXXXXX&apiVersion=34.0&refreshToken=XXXXXXXXXXXXXXXXX&clientId=XXXXXXXXXXXXXXXXX&clientSecret=XXXXXXXXXXXXXXXXX&jobId=75028000000MCv9AAG

Top