Connects to Salesforce from Ballerina.
The Salesforce connector allows you to perform CRUD operations for SObjects, query using SOQL, search using SOSL, and describe SObjects and organizational data through the Salesforce REST API. Also it supports insert, upsert, update, query and delete operations for CSV, JSON and XML data types which provides in Salesforce bulk API. It handles OAuth 2.0 authentication.
SObject Operations
The wso2/sfdc46
module contains operations to do CRUD operations for standard and customized SObjects. It can create,
get, update, and delete SObjects via SObject IDs, and upsert via external IDs.
SOQL & SOSL Operations
The wso2/sfdc46
module contains operations that query using SOQL and search using SOSL. This allows for complex
operations using SObjects relationships.
Describe Operations
The wso2/sfdc46
module contains operations that describe SObjects, organizational data, available resources, APIs, and
limitations for organizations.
Bulk Operations
The wso2/sfdc46
module contains insert, upsert, update, query and delete asynchronous bulk operations for CSV, JSON
and XML data types.
Version | |
---|---|
Ballerina Language | 1.0.1 |
Salesforce REST API | v46.0 |
First, import the wso2/sfdc46
module into the Ballerina project.
import wso2/sfdc46;
Instantiate the connector by giving authentication details in the HTTP client config, which has built-in support for BasicAuth and OAuth 2.0. Salesforce uses OAuth 2.0 to authenticate and authorize requests. The Salesforce connector can be instantiated in the HTTP client config using the access token or using the client ID, client secret, and refresh token.
Obtaining Tokens
-
Visit Salesforce and create a Salesforce Account.
-
Create a connected app and obtain the following credentials:
- Base URL (Endpoint)
- Access Token
- Client ID
- Client Secret
- Refresh Token
- Refresh Token URL
-
When you are setting up the connected app, select the following scopes under Selected OAuth Scopes:
- Access and manage your data (api)
- Perform requests on your behalf at any time (refresh_token, offline_access)
- Provide access to your data via the Web (web)
-
Provide the client ID and client secret to obtain the refresh token and access token. For more information on obtaining OAuth2 credentials, go to Salesforce documentation.
Create Salesforce client
You can define the Salesforce configuration and create Salesforce client as mentioned below.
// Create Salesforce client configuration by reading from config file.
sfdc46:SalesforceConfiguration sfConfig = {
baseUrl: "<EP_URL>",
clientConfig: {
accessToken: "<ACCESS_TOKEN>",
refreshConfig: {
clientId: "<CLIENT_ID>",
clientSecret: "<CLIENT_SECRET>",
refreshToken: "<REFRESH_TOKEN>",
refreshUrl: "<REFRESH_URL>"
}
}
};
// Create the Salesforce client.
sfdc46:Client salesforceClient = new(sfConfig);
If you want to add your own key store to define the secureSocketConfig
, change the Salesforce configuration as
mentioned below.
// Create Salesforce client configuration by reading from config file.
sfdc46:SalesforceConfiguration sfConfig = {
baseUrl: "<EP_URL>",
clientConfig: {
accessToken: "<ACCESS_TOKEN>",
refreshConfig: {
clientId: "<CLIENT_ID>",
clientSecret: "<CLIENT_SECRET>",
refreshToken: "<REFRESH_TOKEN>",
refreshUrl: "<REFRESH_URL>"
}
},
secureSocketConfig: {
trustStore: {
path: "<TRUSTSTORE_PATH>",
password: "<TRUSTSTORE_PASSWORD>"
}
}
};
Salesforce CRUD Operations
The createAccount
remote function creates an Account SObject. Pass a JSON object with the relevant fields needed for
the SObject Account.
json account = { Name: "ABC Inc", BillingCity: "New York" };
string|sfdc46:ConnectorError createReponse = salesforceClient->createAccount(account);
The response from createAccount
is either the string ID of the created account (if the account was created
successfully) or ConnectorError
(if the account creation was unsuccessful).
if (createReponse is string) {
io:println("Account id: " + createReponse);
} else {
io:println(createReponse.detail()?.message.toString());
}
The getQueryResult
remote function executes a SOQL query that returns all the results in a single response or if it
exceeds the maximum record limit, it returns part of the results and an identifier that can be used to retrieve the
remaining results.
string sampleQuery = "SELECT name FROM Account";
sfdc46:SoqlResult|sfdc46:ConnectorError response = salesforceClient->getQueryResult(sampleQuery);
The response from getQueryResult
is either a SoqlResult record with total size, execution status, resulting records,
and URL to get next record set (if query execution was successful) or ConnectorError
(if the query execution
was unsuccessful).
if (response is sfdc46:SoqlResult) {
io:println("TotalSize: ", response.totalSize.toString());
io:println("Done: ", response.done.toString());
io:println("Records: ", response.records.toString());
} else {
io:println("Error: ", response.detail()?.message.toString());
}
The createLead
remote function creates a Lead SObject. It returns the lead ID if successful or
ConnectorError
if unsuccessful.
json lead = {LastName:"Carmen", Company:"WSO2", City:"New York"};
string|sfdc46:ConnectorError createResponse = salesforceClient->createLead(lead);
if (createResponse is string) {
io:println("Lead id: " + createResponse);
} else {
io:println("Error: ", createResponse.detail()?.message.toString());
}
Salesforce Bulk Operations
The createSalesforceBulkClient
remote function creates the salesforce bulk client which facilitates bulk operations.
Bulk client can create appropriate operator Corresponding to the data type. The createCsvInsertOperator
remote
function creates Insert operator for CSV content type.
// Create salesforce bulk client.
sfdc46:SalesforceBulkClient sfBulkClient = salesforceClient->createSalesforceBulkClient();
// Create CSV insert operator for object type `Contact`.
sfdc46:CsvInsertOperator|sfdc46:ConnectorError csvInsertOperator = sfBulkClient->createCsvInsertOperator("Contact");
insert
remote function creates a insert batch using CSV content. CSV content can be passed as a string
or
io:ReadableByteChannel
as given below.
// Upload the CSV contacts as a string.
string contacts = "description,FirstName,LastName,Title,Phone,Email,My_External_Id__c
Created_from_Ballerina_Sf_Bulk_API,John,Michael,Professor Grade 04,0332236677,john434@gmail.com,301
Created_from_Ballerina_Sf_Bulk_API,Peter,Shane,Professor Grade 04,0332211777,peter77@gmail.com,302";
sfdc46:BatchInfo|sfdc46:ConnectorError batchUsingCsv = csvInsertOperator->insert(contacts);
// Upload CSV contacts as a file.
io:ReadableByteChannel|io:Error rbc = io:openReadableFile("path/to/the/file/contacts.csv");
if (rbc is io:ReadableByteChannel) {
sfdc46:BatchInfo|sfdc46:ConnectorError batchUsingCsvFile = csvInsertOperator->insert(rbc);
// close channel.
var cr = rbc.close();
if (cr is error) {
io:println("Error occured while closing the channel: " + cr.toString());
}
} else {
io:println("Error occurred while reading file: " + rbc.toString());
}
closeJob
and abortJob
remote functions close and abort CSV insert job respectively. When a job is closed, no more
batches can be added. When a job is aborted, no more records are processed. If changes to data have already been
committed, they aren’t rolled back.
// Close job.
sfdc46:JobInfo|sfdc46:ConnectorError closedJob = csvInsertOperator->closeJob();
// Abort job.
sfdc46:JobInfo|sfdc46:ConnectorError abortedJob = csvInsertOperator->abortJob();
getJobInfo
remote function get all details for an existing job. getBatchInfo
remote function get information about
an existing batch. getAllBatches
remote function get information about all batches in a job.
// Get job information.
sfdc46:JobInfo|sfdc46:ConnectorError job = csvInsertOperator->getJobInfo();
// Get batch ID using sfdc46:BatchInfo record.
string batchId = batchUsingCsv.id;
// Get batch information.
sfdc46:BatchInfo|sfdc46:ConnectorError batchInfo = csvInsertOperator->getBatchInfo(batchId);
// Get information of all batches of this csv insert job.
sfdc46:BatchInfo[]|sfdc46:ConnectorError allBatchInfo = csvInsertOperator->getAllBatches();
getBatchRequest
remote function gets the batch request uploaded to the csv insert job. getResult
remote
function get results of a batch that has completed processing.
// Retrieve the csv batch request.
string|sfdc46:ConnectorError batchRequest = csvInsertOperator->getBatchRequest(batchId);
// Get batch result as csv.
int noOfRetries = 5; // Number of times trying to get the results.
int waitTime = 3000; // Time between two tries in milli-seconds.
sfdc46:Result[]|sfdc46:ConnectorError batchResult = csvInsertOperator->getResult(batchId, noOfRetries, waitTime);
Likewise Salesforce bulk client provides following operators:
- CSV
- insert operator
- upsert operator
- update operator
- query operator
- delete operator
- JSON
- insert operator
- upsert operator
- update operator
- query operator
- delete operator
- XML
- insert operator
- upsert operator
- update operator
- query operator
- delete operator