Salesforce Rest API Connector Example¶

The Salesforce REST Connector allows you to work with records in Salesforce, a web-based service that allows organizations to manage contact relationship management (CRM) data. You can use the Salesforce connector to create, query, retrieve, update, and delete records in your organization's Salesforce data. The connector uses the Salesforce REST API to interact with Salesforce.

What you'll build¶

This example explains how to use the Salesforce client to connect with the Salesforce instance and perform the following operations:

Create an account.

The user sends the request payload that includes sObjects (any object that can be stored in the Lightning platform database), to create a new Account object in Salesforce. This request is sent to the integration runtime by invoking the Salesforce connector API.

Execute a SOQL query to retrieve the Account Name and ID in all the existing accounts.

In this example use the Salesforce Object Query Language (SOQL) to search stored Salesforce data for specific information which is created under sObjects.

Using Salesforce Rest Connector

The user calls the Salesforce REST API. It invokes the create sequence and creates a new account in Salesforce. Then through the retrieve sequence, it displays all the existing account details to the user.

If you do not want to configure this yourself, you can simply get the project and run it.

Configure the connector in WSO2 Integration Studio¶

Connectors can be added to integration flows in WSO2 Integration Studio. Once added, the operations of the connector can be dragged onto your canvas and added to your sequences.

Import the connector¶

Follow these steps to set up the Integration Project and the Connector Exporter Project.

Open WSO2 Integration Studio and create an Integration Project.
Right-click the project that you created and click on Add or Remove Connector -> Add Connector. You will get directed to the WSO2 Connector Store.
Search for the specific connector required for your integration scenario and download it to the workspace.
Click Finish, and your Integration Project is ready. The downloaded connector is displayed on the side palette with its operations.
You can drag and drop the operations to the design canvas and build your integration logic.
Right click on the created Integration Project and select New -> Rest API to create the REST API.

Add integration logic¶

First create an API, which will be where we configure the integration logic. Right click on the created Integration Project and select, New -> Rest API to create the REST API. Specify the API name as salesforcerest and API context as /salesforcerest.
Now, we will add the relevant Salesforce REST operations to create an account and retrieve data.
Navigate into the Palette pane and select the graphical operations icons listed under Salesforcerest Connector section. Then, drag and drop the 'create' operation into the Design pane.
Now, when you select the create operation on the canvas, the properties window will appear. Create a connection from the properties window by clicking on the '+' icon as shown below.

In the pop-up window, following parameters must be provided. See the Salesforce REST Connector reference page for more information.
- Connection Name - A Unique name for the Salesforce REST connection.
- Connection Type - Type of the connection which specifies the protocol to be used.
- Access Token - The access token to authenticate your API calls.
- API Version - The version of the Salesforce API.
- Host Name - SalesforceOAuth endpoint when issuing authentication requests in your application.
- Refresh Token - The refresh token that you received to refresh the API access token.
- Refresh Token Endpoint - The endpoint of the refresh token that you invoke to refresh the API access token.
- Client Secret - The consumer secret of the connected application that you created.
- Client ID - The consumer key of the connected application that you created.
- API URL - The instance URL for your organization.
- Timeout - Timeout duration of the API request.
- Username - The username for the salesforce.
- Password - The password for Salesforce (need to append the password with security key).
- Blocking - Set to true to perform the blocking invocations to Salesforce.
Following values can be provided to connect to Salesforce.
- Connection Name - SALESFORCEREST_CONNECTION_1
- Connection Type - Init Saleforcerest Connection
- Access Token - <your_salesforce_access_token>
- API Version - v59.0.
- Host Name - https://login.salesforce.com
- Refresh Token - <your_salesforce_refresh_token>
- Refresh Token Endpoint - <your_salesforce_refresh_token_endpoint>
- Client Secret - <your_salesforce_client_secret>
- Client ID - <your_salesforce_client_id>
- API URL - https://<your_salesforce_instance_name>.salesforce.com
- Timeout - 30000
- Username - <your_salesforce_username>
- Password - <your_salesforce_password>
- Blocking - false
After the connection is successfully created, select the created connection as 'Connection' from the drop down in the properties window.
Set up the create operation.
1. By using this create operation we are going to create an sObject in the Salesforce account. An sObject represents a specific table in the database that you can discretely query. It describes the individual metadata for the specified object. Please find the create operation parameters listed here.
  - sObjectName : Name of the sObject that you need to create in Salesforce.
  - fieldAndValue : The field and value you need to store in the created Salesforce sObject.
2. While invoking the API, the above two parameters values come as a user input. You can provide the expressions as below in the properties window to obtain respective values from the JSON request payload.
  - sObject Name - json-eval($.sObjectName)
  - Field and Value - json-eval($.fieldAndValue)
Set up the retrieve operation.
1. To retrieve data from the created objects in the Salesforce account, you need to add the query operation next to the create operation. Please find the query operation parameters listed here.
  - queryString : This variable contains specified SOQL query. In this sample this SOQL query executes to retrieve id and name from created Account. If the query results are too large, the response contains the first batch of results.
2. Navigate into the Palette pane and select the graphical operations icons listed under Salesforce Connector section. Then drag and drop the query operation into the Design pane.
3. Select the query operation and add the Connection and id, name from Account query string to the properties section shown as bellow.
Finally, drag and drop the Respond Mediator to send the message back to the client as a response.

Now, you can switch into the Source view and check the complete XML configuration files of the created API and the Local Entry.

salesforcerest.xml

<?xml version="1.0" encoding="UTF-8"?>
<api context="/salesforcerest" name="salesforcerest" xmlns="http://ws.apache.org/ns/synapse">
    <resource methods="POST">
        <inSequence>
            <salesforcerest.create configKey="SALESFORCEREST_CONNECTION_1">
                <sObjectName>{json-eval($.sObjectName)}</sObjectName>
                <fieldAndValue>{json-eval($.fieldAndValue)}</fieldAndValue>
            </salesforcerest.create>
            <salesforcerest.query configKey="SALESFORCEREST_CONNECTION_1">
                <queryString>id, name from Account</queryString>
            </salesforcerest.query>
            <respond/>
        </inSequence>
        <outSequence/>
        <faultSequence/>
    </resource>
</api>

SALESFORCEREST_CONNECTION_1.xml

<?xml version="1.0" encoding="UTF-8"?>
<localEntry key="SALESFORCEREST_CONNECTION_1" xmlns="http://ws.apache.org/ns/synapse">
    <salesforcerest.init>
        <hostName>https://login.salesforce.com</hostName>
        <connectionType>init</connectionType>
        <timeout>3000</timeout>
        <apiVersion>v59.0</apiVersion>
        <apiUrl>https://xxxx.salesforce.com</apiUrl>
        <clientSecret>xxxx</clientSecret>
        <clientId>xxxx</clientId>
        <name>SALESFORCEREST_CONNECTION_1</name>
        <refreshToken>xxxx</refreshToken>
    </salesforcerest.init>
</localEntry>

Get the project¶

You can download the ZIP file and extract the contents to get the project code.

Tip

You may need to update the value of the access token/refresh token and make other such changes before deploying and running this project.

Deployment¶

Follow these steps to deploy the exported CApp in the integration runtime.

Deploying on Micro Integrator

You can copy the composite application to the <PRODUCT-HOME>/repository/deployment/server/carbonapps folder and start the server. Micro Integrator will be started and the composite application will be deployed.

You can further refer the application deployed through the CLI tool. See the instructions on managing integrations from the CLI.

Click here for instructions on deploying on WSO2 Enterprise Integrator 6

You can copy the composite application to the <PRODUCT-HOME>/repository/deployment/server/carbonapps folder and start the server.
WSO2 EI server starts and you can login to the Management Console https://localhost:9443/carbon/ URL. Provide login credentials. The default credentials will be admin/admin.
You can see that the API is deployed under the API section.

Testing¶

Save a file called data.json with the following payload.

{
    "sObjectName":"Account",
    "fieldAndValue": {
        "name": "Engineers",
        "description":"This Account belongs to WSO2"
    }
}

Invoke the API as shown below using the curl command. Curl application can be downloaded from here.

curl -X POST -d @data.json http://localhost:8280/salesforcerest --header "Content-Type:application/json"

You will get a set of account names and the respective IDs as the output.

What's Next¶

To customize this example for your own scenario, see Salesforce REST Connector Configuration documentation for all operation details of the connector.