Salesforce Connector

Introduction

Salesforce is a cloud-based CRM software platform, used in applications varying from sales lead tracking to order and inventory management.

Purpose

This document details the Salesforce REST API Connector found on the Tulip Library. Once configured, these Connector Functions can be used to retreive, query, and modify Salesforce data from a Tulip App.

API Documentation

Documentation for the Salesforce REST API can be found here. Note that some Connector Functions included in this article accomplish queries using SOQL (Salesforce Object Query Language), the full syntax of which is documented here.

First Time Set-Up

Salesforce API Authentication follows OAuth 2.0 standards.
The following process outlines how to generate a refresh token, which will be then used by any Tulip App to retrieve the access token needed to successfully connect to Salesforce.

1. Create a Connected App in Salesforce. To do so, navigate to the "Setup" space in Salesforce. Then, navigate to PLATFORM TOOLS >> Apps >> Connected Apps >> Manage Connected Apps.
2. Create a new Connected App. Include:
   a. any scopes required by your application, but be sure to include refresh_token.
   b. Select Enable OAuth Settings, and enter the Callback URL as https://login.salesforce.com/services/oauth2/success.
3. Once complete, click Manage Consumer Details to see your "Consumer Key" and "Consumer Secret". These will be used later.
4. Now in Tulip, open the Connector Function [Setup] Get Auth Code URL. Copy and paste the "Consumer Key" generated in Step 3 above as the Query Parameter client_id.
5. "Run" the Connector Function.
6. Observe that a URL has been generated as an "Output" of the Connector. Paste this URL into your browser window.
7. Complete the authentication prompt that appears to successfully authorize Tulip to interact with your Salesforce instance.
8. If successful, your browser should redirect to a new page that says Remote Access Application Authorization. The Authorization Code can be found in the URL of this page.
   For example, in the URL https://login.salesforce.com/services/oauth2/success?code=asdf1234 the Authorization Code is asdf1234.
9. Save this Authorization Code. Note that the code must end in two equals symbols: == . If the code ends in %3D%3D, remove these characters and replace with == .
10. Navigate to the [Setup] Get Refresh Token Tulip Connector Function. In the Query Parameters, paste in all the information that has been gathered above:
    • grant_type= authorization_code
    • redirect_uri= https://login.salesforce.com/services/oauth2/success
    • client_id= the Consumer Key from Step 3 above
    • client_secret= the Consumer Secret from Step 3 above
    • code= the Authorization Code from Step 9 above
11. Run this Connector, and save the the refresh_token that appears in the response.
12. Finally, navigate to the [Auth] Get Access Token Connector Function. Fill out the following Query Parameters:
    • grant_type= authorization_code
    • client_id= the Consumer Key from Step 3 above
    • client_secret= the Consumer Secret from Step 3 above
    • refresh_token= the Refresh Token from Step 10 above
13. Run the Connector. Note that the response includes an access_token, which is mapped as an output. Save the Connector to save the Refresh Token

Once this Function is able to generate an access_token, setup is complete! This access_token may now be used in any subsequent Connector Function for as long as the time-out settings configured in Step 2 allow.

Tulip Connection Details

To enable your Connectors to interface with Salesforce, input your Salesforce Instance's subdomain as the "Default Subdomain", under the Connector's Connection Details.
For example, if the Salesforce instance can be found at sample.my.salesforce.com then the default subdomain should be sample.my.

Note that all Connector Functions here are built to work with Salesforce REST API v46.0.

Connector Functions

Two primary types of Connector exist: object-type and query-type connectors.
Note that both Connectors require an access_token, so be sure to run [Auth] Get Access Token in your app before these! It's commonly recommended to generate a new Access Token when the app or process starts, and save it to an App Variable for later use.

Object-Type Connectors

• Return all fields of the Object in question.
• Use endpoint ./services/data/v46.0/sobjects/<Object Name>/<Object ID>
• Example: Connector [Opportunity] Get All Fields

Query-Type Connectors

• Return only the fields specified in the query.
• Can return linked (e.g. the Account Name related to an Opportunity) or aggregate (e.g. a count of records) information.
• Use endpoint ./services/data/v46.0/query
• Require writing a query using SOQL (documentation here).
• Example: Connector [Order] Get All Orders of Status

Included Connector Functions

The following Connector Functions are included in this pack and are intended to serve as an introduction to the functions possible via the Salesforce API:

• [Setup] Get Auth Code URL & [Setup] Get Refresh Token
  • Used only for first-time setup. See above for more information.
• [Auth] Get Access Token
  • Used to generate an Access Token, which must be included in all subsequent Connector Functions.
• [Opportunity] functions:
  • Get All Fields
    • Returns all fields of the Opportunity queried. Requires Access Token and Opportunity ID.
  • Change Stage
    • Updates the Stage of the indicated Opportunity to the specified value.
• [Order] functions:
  • Get All Orders of Status
    • Returns a list of all Orders of a specified Status.
  • Count Orders of Status
    • Returns a count of all Orders of a specified Status.
  • Get Order Number from ID
    • Returns an Order Number from a specified Order ID.

To modify these functions to fit your needs, note the advice below:

1. To modify object-type Connector Functions, simply change the Object indicated in the URL. Add or remove new outputs as necessary.
2. To modify query-type Connector Functions, all changes must be made in the Query. This can be found in the Query Parameters, with the key q.
   1. Tip: limit the number of responses from a Query with the function LIMIT(number_of_responses)

Did you find what you were looking for?

You can also head to community.tulip.co to post your question or see if others have faced a similar question!