> ## Documentation Index
> Fetch the complete documentation index at: https://docs.refold.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Build Salesforce Integration
In this guide, we will walk through the essential steps required to build a Salesforce integration using the Refold platform. This process involves three major steps i.e. User Authentication with Salesforce, Creating Workflows and Using workflows for users.
## Authenticating with Salesforce integration
To get started, first you need to enable the Salesforce integration in your account and also setup some basic processes.
### Step 1: Enable the Salesforce App
After setting up your account, the next step is to enable the Salesforce app in your Refold account.
Apps cannot be enabled using the API. You will need to enable the app through the UI.
To enable the Salesforce app:
Navigate to `Apps` in Refold and search for **Salesforce** and enable the app by clicking on the `Go Live` button in the top right corner.
Now, go to `Settings` and provide the **Client ID** and **Client Secret** of your Salesforce OAuth app and click on `Save`.
Follow the steps given [here](https://docs.gocobalt.io/resources/integration-providers/salesforce) to get your credentials.
Once the app is enabled, you can proceed to create and manage workflows and linked accounts associated with Salesforce.
### Step 2: Create a Linked Account
A Linked Account in Refold represents the end-users or customers who will use the integration through the platform. Each Linked Account requires a unique linked\_account\_id, which typically corresponds to an ID from your internal data model (e.g., a user or account ID).
Learn more about Linked Accounts [here](/build/basics/linked_account).
To upsert (create or update) a Linked Account, use the following API call:
```bash cURL theme={null}
curl --request PUT \
--url https://api.gocobalt.io/api/v2/public/linked-account \
--header 'Content-Type: application/json' \
--header 'x-api-key: ' \
--data '{
"linked_account_id": "",
"name": ""'
```
| Param | Required | Type | Description |
| ------------------- | --------- | ------ | -------------------------- |
| linked\_account\_id | Mandatory | String | Unique customer identifier |
| name | Optional | String | Name of the customer |
You can check the Linked Accounts in your Refold account by navigating to the **Linked Accounts** section in the side menu.
Once the Linked Account is successfully created or updated, it will be ready for authentication in the next step.
### Step 3: Generate Token
After creating a Linked Account, the next step is to generate a session token. Session tokens help protect your Refold API key and manage end-customer tokens more securely.
To create a session token, use the following API call:
```JavaScript cURL theme={null}
curl --request POST \
--url https://api.gocobalt.io/api/v2/public/session-token \
--header 'Content-Type: application/json' \
--header 'x-api-key: ' \
--data '{
"linked_account_id": ""
}'
```
This session token will be included in subsequent requests to Refold APIs to authenticate and authorize the actions.
### Step 4: Open Hosted Portal Auth Flow
Next, you will need to generate a Hosted URL that your users will use to authenticate with Salesforce. Refold securely stores the credentials and handles API calls on behalf of your users.
Use the following API call to generate the Hosted URL:
```JavaScript cURL theme={null}
curl --request POST \
--url https://api.gocobalt.io/api/v2/public/connect-url \
--header 'Content-Type: application/json' \
--header 'x-api-key: ' \
--data '{
"color": "",
"bgColor": "",
"name": ""
}'
```
The response will return a Hosted URL that your users can visit to authenticate and connect their Salesforce accounts.
Hosted Portal is a no-code solution provided by Refold that removes the need to build your own UI for handling integration authentication and configuration.
### Step 5: Perform OAuth Authentication
Visit the Hosted URL provided in the API response. The Hosted Portal will display all the integrations you have enabled, including Salesforce.
To authenticate:
* Navigate to the Salesforce integration in the portal.
* Click Connect to begin the authentication process and allow consent to permissions requested.
* After completing the flow, you will be redirected back to the Hosted Portal with a confirmation that the account is successfully connected.
You have successfully authenticated with Salesforce integration.
The next step is to create workflows for your use-case.
## Creating Workflows in Salesforce
There are 3 major categories of workflows that you can create in any integration.
Sync data from Salesforce to your system.
Create data on Salesforce from your system.
Keep the data between Salesforce and your system in sync.
Let's look at a sample workflow for each case.
#### Data Import from Salesforce
Consider a use-case where you want to sync all the opportunities present in Salesforce to your system.
In the Salesforce integration, go to `Workflows` and create a new workflow by clicking on `+Add Workflow` button and name it as `Sync Opportunities`.
Follow the steps given to build the workflow:
All workflows start with a trigger, which determines when the workflow will run and how data is passed into the workflow.
For this workflow we will use the Event Based trigger.
Learn more about the triggers and its types [here](https://docs.gocobalt.io/build/workflow/triggering_workflow).
Click on the `Start Node`, select your native app option and click on `+ Create New Event`.
Give a name to your event and keep the payload as an empty object.
Now to fetch all the opportunities present in your user's account, we need to call Salesforce API.
Click on `Nodes` option in the top right and drag the Salesforce Node from **Native Apps** section to the workflow builder. Connect this node with Start Node.
Click on the Salesforce Node and select `Get Entity with SOQL` action.
Add the following under `SOQL query` field and click on `Save`.
```
SELECT Id,Amount,AccountId, CloseDate,ContactId,Description,ExpectedRevenue,LeadSource, Name, OwnerId, Probability,StageName,Type FROM Opportunity
```
You can provide any additonal fields that you want to fetch about opportunities from Salesforce by adding it to this query.
We have fetched all the opportunities, but you might require to structure it as a payload which your platform can receive. Let's do this using **Custom Code** node.
Drag the Custom Code from the Utility Nodes section onto the workflow builder and connect it with Salesforce node.
Click on `+ Map Fields` under Input Parameters, add key name as `deals` and in value we will provide the response received through Salesforce node which will be restructured.
In `Value`, select **Nodes** tab under Insert Variable and click on `+` of the Salesforce Node.
You can now do mapping using JavaScript code. Try the sample code provided below:
```
function yourFunction(params) {
const res = params.deals.map(ele=>{
const output = {
id: ele.Id,
title: ele.Name,
description: ele.Description || 'Description not available',
close_date: ele.CloseDate,
amount: ele.Amount,
expected_revenue: ele.ExpectedRevenue,
status: ele.StageName
}
return output
})
return {"result": res || [] }
}
```
You have successfully fetched all opportunities and structured the payload. Now to receive it in your server, you need to configure an API Proxy.
In Refold Dashboard, navigate to `Developer` > `API Proxies` and click on `New Action`. Configure an API endpoint, where you want to receive the response.
If you want to test, go to [webhook.site](https://webhook.site/) and copy `Your unique URL` and configure this as a POST Request and `Save`.
Learn more about API Proxies [here](https://docs.gocobalt.io/build/basics/proxies).
From Native Apps nodes, add your org's Node and connect it with Custom Code.
Click on the node and select the API Proxy that you created from the Actions. Add the response from Custom Code node in data field and click on `Save`.
Ensure that you add a field in the API Proxy where you can pass the JSON data and then added it to the API Call body as well in the POST request.
Hurray!!
You have successfully created a Salesforce workflow to sync all the opportunities to your system.
#### Push Data to Salesforce
Consider a use-case where you want to create a contact present in your system to Salesforce.
This workflow will be fired when you send an Event with the payload of the contact to be added.
In the Salesforce integration, go to `Workflows` and create a new workflow by clicking on `+Add Workflow` button and name it as `Create New Contact`.
Follow the steps given to build the workflow:
All workflows start with a trigger, which determines when the workflow will run and how data is passed into the workflow.
For this workflow we will use the Event Based trigger.
Learn more about the triggers and its types [here](https://docs.gocobalt.io/build/workflow/triggering_workflow).
Click on the `Start Node`, select your native app option and click on `+ Create New Event`.
Give a name to your event and provide all the data related to the contact in the payload.
Now to create a new contact in Salesforce, we need to call Salesforce API.
Click on `Nodes` option in the top right and drag the Salesforce Node from **Native Apps** section to the workflow builder. Connect this node with Start Node.
Click on Salesforce Node and add the `Create Contact` action.
To provide the data in all the fields from your Event payload, just click on a field and from the **Event** tab under Insert Variable, select the fields from the body that you sent as payload.
Ensure that all the mandatory fields in the action are filled, else the Salesforce API will give error.
Hurray!!
You have successfully created a Salesforce workflow to create a new contact.
#### 2-way sync between Salesforce and you (Webhooks)
For bi-directional sync, usually three workflows are required:
* **Workflow for Initial sync** where all the records are fetched from Salesforce.
This is the same workflow as Data Import workflow that we created [here](/implementation/examples/build_salesforce#data-import-from-salesforce).
* **Workflow to push record** in Salesforce when a new record is created on your platform.
We created this workflow of Push Data [here](/implementation/examples/build_salesforce#push-data-to-salesforce).
* **Workflow to update records** in your system whenever a contact gets created or updated in Salesforce.
To perform a real time update whenever a change happens in Salesforce, we will use Salesforce Webhook as a trigger for our workflow.
Follow the steps given below to setup your workflow:
In the Start Node, select **Salesforce** as the trigger and select `Contact Created` event.
Similarly, you can use the **Contact Updated** event to get notified whenever a contact is updated in Salesforce.
By using the Contact Created trigger, you will receive data as an event payload about any new contact created in Salesforce in real time.
Send the data that we received about the new contact to your system to perform real time sync.
From Native Apps nodes, add your org's Node and connect it with Start Node.
Click on the node and select the API Proxy that you created from the Actions to receive new contact info. Add the response from Event using **Insert Variables** and click on `Save`.
Ensure that you add a field in the API Proxy where you can pass the data and then added it to the API Call body as well in the POST request.
Hurray!
You have successfully created a workflow which will inform you whenever a new contact is created in Salesforce.
You have successfully created the workflows for your use case.
Next step is to enable and execute those workflows for your Linked Accounts.
## Executing the Workflows
To run these workflows for your users or Linked Accounts, you need to do the following steps:
Config is a customization that you store for each integration of your end-customers.
## Create Config
You can create config for the Linked Account through the Hosted Portal SDKs or using the APIs.
You can use the **.config()** method or the [Create Config API](https://docs.gocobalt.io/api-reference/config/find-or-create-config) which returns the specified config or creates one if it doesn't exist for the Linked Account.
Make a request with the `Application Slug` and `linked_account_id` as mandatory fields for it. You can request in the following way:
```JavaScript .config() theme={null}
cobalt.config({
slug: "salesforce",
config_id: "OPTIONAL_ID_FOR_THIS_CONFIG",
labels: {}, // optional dynamic labels
})
```
```JavaScript cURL theme={null}
curl --request POST \
--url https://api.gocobalt.io/api/v2/public/config \
--header 'Content-Type: application/json' \
--header 'linked_account_id: ' \
--header 'x-api-key: ' \
--data '{
"slug": "",
"config_id": "",
"labels": {}
}'
```
It will return information about config of the application for the Linked Account and provides you with all the published workflows and settings input for the user required to execute the workflow.
```JavaScript Response theme={null}
{
"slug": "salesforce",
"config_id": "OPTIONAL_ID_FOR_THIS_CONFIG",
"fields": [],
"workflows": [
{
"id": "64d1fac58716dc5065127ffe",
"name": "Sync Opportunities",
"description": "",
"enabled": false,
"fields": []
}
],
"field_errors": []
}
```
Now you need to enable the workflow for your Linked account. You can either ask the user to enable them or you can do so for them by using the [Update Config API](https://docs.gocobalt.io/api-reference/config/update-config) or **.updateconfig()** method.
Make the following request:
```JavaScript Method theme={null}
cobalt.updateConfig({
slug: "salesforce",
config_id: "OPTIONAL_ID_FOR_THIS_CONFIG",
fields: {
"64da0b57c9ae95561bb0a24d": "C044U7Q074J"
},
workflows: [
{
id: "64d1fac58716dc5065127ffe",
enabled: true,
fields: {
"64da0b57c9ae95561bb0a24f": "C044U7Q074J"
}
}
]
})
```
```JavaScript cURL theme={null}
curl --request PUT \
--url https://api.gocobalt.io/api/v2/public/config \
--header 'Content-Type: application/json' \
--header 'linked_account_id: ' \
--header 'x-api-key: ' \
--data '{
"slug": "",
"config_id": "",
"fields": {
"64abea6d941ba774d124b19c": ""
},
"workflows": [
{
"id": "",
"enabled": true,
"fields": {
"64abea6d941ba774d124b19c": ""
}
}
]
}'
```
In response, you get the updated config information for the application.
Once the required workflows are enabled, you need to fire event to start execution. You can use the [Trigger Event for app](https://docs.gocobalt.io/api-reference/event/trigger-event) API with the following request:
```JavaScript cURL theme={null}
curl --request POST \
--url https://api.gocobalt.io/api/v2/public/event/:slug \
--header 'Content-Type: application/json' \
--header 'linked_account_id: ' \
--header 'x-api-key: ' \
--data '{
"event": "",
"payload": {}
}'
```
Once the workflow execution has been fired, you can check the Logs of the workflow [here](https://app.gocobalt.io/logs).
Learn more about logs and observability [here](https://docs.gocobalt.io/maintain/logs).
Congratulations!!
You have successfully created a Salesforce integration and executed it for your users.