--- title: "Salesforce Pipeline Integration Setup & Troubleshooting" slug: "salesforce-pipeline-integration-setup" description: "Connect Salesforce to GovDash seamlessly with our integration guide. Learn about sync options, setup steps, and linking phases for efficient management." tags: ["Integration", "Salesforce", "Custom Fields", "Pipeline", "Troubleshooting"] updated: 2026-11-04T21:29:20Z published: 2026-11-04T21:29:20Z canonical: "support.govdash.com/salesforce-pipeline-integration-setup" --- > ## Documentation Index > Fetch the complete documentation index at: https://support.govdash.com/llms.txt > Use this file to discover all available pages before exploring further. # Salesforce Pipeline Integration Setup & Troubleshooting > [!CAUTION] > Before you begin > > In order to successfully connect Salesforce to GovDash, you must be a Salesforce administrator, and a GovDash administrator. This is required in order to grant GovDash permission to access your Salesforce. --- ## Connecting Salesforce To connect Salesforce to GovDash: 1. Access the [**Salesforce Integration page**](https://dashboard.govdash.us/settings/integrations) in GovDash. 2. Click **Connect Salesforce** on the right hand side. 3. Login to your Salesforce account that you want to connect to GovDash. 4. Salesforce will process the connection, and bring you back to GovDash for configuration. --- ## Initial Configuration and Sync Settings GovDash provides multiple options for syncing your Salesforce opportunities into your GovDash Pipeline. You can configure your Salesforce connection and sync settings on the [**Capture Settings**](https://dashboard.govdash.us/settings/capture) page, located within your GovDash Settings. ### Create Only Sync This setting will only create opportunities in GovDash from your Salesforce pipeline, it will not overwrite any of your opportunities within GovDash. ### Override Sync This setting will move your opportunities within GovDash to the stage that they are currently set to within Salesforce, based on your linked/mapped phases. This option is useful for teams where Salesforce will be your source of truth, and you want GovDash to stay in sync with changes made in Salesforce. ### Bidirectional Salesforce Sync (Webhooks) GovDash supports bidirectional sync to Salesforce through webhooks. This will allow GovDash to communicate opportunity creation, deletion, and updates directly to your Salesforce pipeline. For more information on how to configure this integration, please [**see our support article here**](/v1/docs/webhooks). --- ## Syncing Opportunities The Salesforce integration offers multiple sync options depending on your needs. ### One Time Sync You can perform a one time sync by selecting the **Sync Salesforce Opportunities** button on the right hand side. You will then be prompted to map your phases from Salesforce to GovDash. As you pick phases, GovDash shows an estimate of how many new opportunities the sync would create. GovDash will then process your sync and let you know once the sync has been successful. If you close the **One-time Sync** window and reopen it, GovDash remembers the phases you picked for up to 2 hours. This sync is preferred if you only wish to bring your opportunities over and not keep your Salesforce phases in sync with GovDash. ![](https://cdn.us.document360.io/104c3542-bffe-46a6-901f-aa7a848851a4/Images/Documentation/image(969).png) ![One-time Sync window with phases mapped and the sync estimate above Sync Opportunities](https://cdn.us.document360.io/104c3542-bffe-46a6-901f-aa7a848851a4/Images/Documentation/one_time_sync_estimate.png) ### Automating Sync This setting allows you to automatically sync your Salesforce opportunities using your set sync setting. This can be enabled by selecting the checkbox under the **Phases** heading after [**linking your phases**](/v1/docs/salesforce-pipeline-integration-setup#linking-phases). The automatic sync will run every **4 hours** and respect the [**Sync Settings**](/v1/docs/salesforce-pipeline-integration-setup#initial-configuration-and-sync-settings) selection you’ve made. ![](https://cdn.us.document360.io/104c3542-bffe-46a6-901f-aa7a848851a4/Images/Documentation/image(968).png) --- ### Linking Phases If you would like to have Salesforce be your source of truth and sync your phases **and** opportunities to GovDash, select the **Link Phases** button under the **Phases** heading. ![](https://cdn.us.document360.io/104c3542-bffe-46a6-901f-aa7a848851a4/Images/Documentation/image(970).png) GovDash will prompt you to map your phases from GovDash to your phases within Salesforce. ![](https://cdn.us.document360.io/104c3542-bffe-46a6-901f-aa7a848851a4/Images/Documentation/image(10).png) You will then be prompted to select any additional phases within Salesforce that you'd like to link to GovDash. ![](https://cdn.us.document360.io/104c3542-bffe-46a6-901f-aa7a848851a4/Images/Documentation/image(33).png) You may rearrange your phases and choose color options in this step, or at any time from the Capture Settings in GovDash. ![](https://cdn.us.document360.io/104c3542-bffe-46a6-901f-aa7a848851a4/Images/Documentation/image(34).png) If you'd like to link your phases and sync your opportunities, select **Link Phases & Sync Opportunities**, otherwise select **Link Phases** to only link your phases to GovDash without a sync. --- ### Tracking/Mapping Salesforce Fields > [!WARNING] > Before You Begin… > > You can create a custom field right from the **Track Salesforce Field** window with **New custom field…**, or set up your custom fields within GovDash before you map your Salesforce fields. Please check our [support article here](/v1/docs/customizing-the-pipeline#adding-and-managing-custom-fields) for guidance. Using the **Track Field** button, you can map additional Salesforce fields to GovDash, such as due dates, descriptions, NAICS codes, opportunity values, and more. ![](https://cdn.us.document360.io/104c3542-bffe-46a6-901f-aa7a848851a4/Images/Documentation/image(541).png) In the **Track Salesforce Field** window, choose your **Salesforce object** and the **Salesforce field** you'd like to map. Then use the **Fills in** drop down to choose where that value goes in GovDash: a standard opportunity field, one of your custom fields, or **New custom field…**. Options that can't hold the selected field's type are grayed out with a short reason. Click **Track Field** to save. > [!NOTE] > Salesforce Object/Table Support > > We currently only support the **Opportunity** table in Salesforce, but this may change in future updates. ![Track Salesforce Field window with Opportunity and a Salesforce field selected and the Fills in list open showing New custom field and grayed out options](https://cdn.us.document360.io/104c3542-bffe-46a6-901f-aa7a848851a4/Images/Documentation/track_salesforce_field_window.png) This will link the fields together, which will sync the data within the opportunity’s fields on your next successful sync. Custom fields that you’ve created in GovDash can be mapped to your Salesforce fields as well! You can also choose **Salesforce Link** as your Salesforce field to fill in a URL custom field with a link to the record in Salesforce. To keep your gate review in step with Salesforce, choose a picklist or checkbox field, select **Gate review status** under **Fills in**, and use **Value mapping** to choose the status each Salesforce value sets. > [!NOTE] > What Happens When Fields Don’t Match? > > If you are trying to map fields that do not contain the same data between GovDash and Salesforce (such as a NAICS selector that doesn’t have the same code layout/description, or Agency list that spells agency names out differently) and a sync is attempted, GovDash will show `null` within that field in your Pipeline opportunity Overview tab. > > We recommend utilizing [Custom Fields](/v1/docs/customizing-the-pipeline#adding-and-managing-custom-fields) within GovDash for these types of fields, which you can map and ensure that the options match between GovDash and Salesforce, which is especially useful for pick lists. > [!CAUTION] > Unsupported Custom Field Types > > Currently there are six unsupported custom field types for mapping to Salesforce. We are working to support these as soon as possible: > > - Number Range > - Currency Range > - Date Range > - Multi-Select > - Formula > - Rating > - Direct Support for Lookup Fields (See [Mapping Lookup Fields to GovDash](/v1/docs/salesforce-pipeline-integration-setup#mapping-lookup-fields-to-govdash) Section for our recommended solution) --- ### Linking Existing GovDash Opportunities to Salesforce Opportunities If you have the same opportunities in your GovDash Pipeline already within Salesforce and you’re setting up the integration, you can link these opportunities together through field and ID mapping using the steps below. This ensures that when Salesforce is synced to GovDash, it is able to identify your opportunities within your GovDash Pipeline and update the existing opportunities without creating new ones. > [!WARNING] > Note > > This will not update opportunities from GovDash → Salesforce without setting up webhooks. Webhooks must be configured before information can be sent out of GovDash to Salesforce. For information on configuring webhooks, [please see our guide here](/v1/docs/webhooks). 1. On the Salesforce side, your team will need to create a new field/column titled **GovDash_Opportunity_ID**. This field will contain the opportunity ID from within GovDash, which will be used to "match" the opportunities upon import/sync to GovDash. 2. For any opportunities that exist between both systems, using this **GovDash_Opportunity_ID** field, enter the opportunity ID of the opportunity within GovDash (found within the URL bar when you're in the opportunity) into the Salesforce side/version. ![](https://cdn.us.document360.io/104c3542-bffe-46a6-901f-aa7a848851a4/Images/Documentation/image(622).png) 3. When configuring the Salesforce integration in GovDash and mapping the fields, ensure that the **GovDash Opportunity ID** field is mapped to the **External CRM Identifier ID**. ![](https://cdn.us.document360.io/104c3542-bffe-46a6-901f-aa7a848851a4/Images/Documentation/image(623).png) 4. Initialize the opportunity sync with the **Override** option. By mapping these fields ahead of time, this ensures that Salesforce has the GovDash ID mapped, which will update the GovDash opportunities with the Salesforce data. --- ## Mapping Lookup Fields to GovDash While the integration doesn’t directly support lookup fields (as these fields in Salesforce reference an ID rather than a readable value), you can use the steps below to create a field that extracts the value from the lookup field into a value that is readable (and mappable) to GovDash, while keeping the two fields completely in sync. ### Creating and Mapping Lookup Field Steps **Before you start: how lookup field naming works** Salesforce uses two different naming patterns for lookup fields, and the formula syntax differs slightly between them. Identifying which one you're working with up front will save time. | **Field type** | **API name pattern** | **Formula reference pattern** | | --- | --- | --- | | Custom lookup | FieldName__c | FieldName__r.Name | | Standard lookup | FieldNameId | FieldName.Name | | User lookup (standard) | OwnerId, CreatedById | Owner.Name, CreatedBy.Name | **In short:** - For custom lookup fields, replace __c with __r to traverse the relationship. - For standard lookup fields, drop the Id suffix. There is no __r involved. ![](https://cdn.us.document360.io/104c3542-bffe-46a6-901f-aa7a848851a4/Images/Documentation/image-AFCP71DQ.png) Standard Salesforce Fields ![](https://cdn.us.document360.io/104c3542-bffe-46a6-901f-aa7a848851a4/Images/Documentation/image-9KJAATLQ.png) Custom Salesforce Fields **Step 1: Find your lookup field's API name** 1. Go to Setup. 2. Go to Object Manager. 3. Click Opportunity 4. Click Fields & Relationships. 5. Under the Data Type column, find the field with the Lookup data type. 6. Click the field name to open its detail page and copy the Field Name (API name) exactly as shown. **How to recognize which pattern you have:** - Ends in __c → custom lookup (e.g., Vehicle__c, Partner__c). - Ends in Id with no underscores → standard lookup (e.g., AccountId, OwnerId). **Step 2: Confirm the lookup object** On the same field detail page, find the Related To value. This tells you what object the lookup points to and which fields are available to reference. For most lookups, the Name field on the related record is what you want to surface. **Step 3: Create the Formula (Text) field** 1. While still in the object's Fields & Relationships page, click New. 2. Select Formula and click Next. 3. Enter a Field Label and Field Name. 4. Set Return Type to Text and click Next. **Step 4: Apply the formula** **Custom lookup fields** *Replace __c with __r and append .Name (or another field on the related object).* | **Lookup field API name** | **Formula** | | --- | --- | | Vehicle__c | Vehicle__r.Name | | Agency_Description__c | Agency_Description__r.Name | | Partner__c | Partner__r.Name | **Standard lookup fields** *Drop the Id suffix and append the field you want from the related record. These are the most common standard lookups on the Opportunity object.* | **Standard lookup** | **API name** | **Formula** | | --- | --- | --- | | Account | AccountId | Account.Name | | Primary Campaign Source | CampaignId | Campaign.Name | | Record Type | RecordTypeId | RecordType.Name | | Price Book | Pricebook2Id | Pricebook2.Name | **User-based fields (Owner, Created By, Last Modified By)** *User lookups don't expose a single Name field, so you typically concatenate first and last name using the & operator. The same patterns apply to CreatedBy and LastModifiedBy.* | **Goal** | **Formula** | | --- | --- | | Full name | Owner.FirstName & " " & Owner.LastName | | Email | Owner.Email | | Username | Owner.Username | **Step 5: Validate and save** 1. Click Check Syntax. You should see No errors. 2. Click Next. 3. Set Field-Level Security if needed. 4. Add the field to your page layout. 5. Save. Once saved, the new Formula (Text) field will be available to map in the GovDash Salesforce integration alongside your other Opportunity fields. --- **Step 6: Map the Field in GovDash** 1. Navigate to **Capture Settings** in Settings 2. Create the corresponding custom field for your new formula fields 3. Click **Track Field**, choose **Opportunity** as the **Salesforce object** and your new formula field as the **Salesforce field**, select your custom field under **Fills in**, and then click **Track Field** to save. 4. On your next sync (whether manual or automatic, depending on your settings), the new formula field data will sync showing the actual value of that lookup field, rather than the key. --- ## Disconnecting Salesforce To disconnect your Salesforce account, select the **Disconnect Salesforce Account** button above the Sync Settings. ![](https://cdn.us.document360.io/104c3542-bffe-46a6-901f-aa7a848851a4/Images/Documentation/image(215).png) --- ## Troubleshooting ****I am receiving an OAuth Error when trying to connect my Salesforce account**** If you see an OAuth error when trying to connect GovDash to Salesforce, especially one that mentions **“app must be installed in org”**, this usually means Salesforce is blocking the connection because the connected app has not yet been approved by an administrator. --- **How to Identify This Issue** You may be experiencing this issue if: - You see an OAuth error after clicking **Connect Salesforce** in GovDash - The browser URL or error message includes: - `app+must+be+installed+in+org` - or similar language about the app not being installed - The Salesforce connection fails immediately, even when logged in as an Admin --- **What to Check First** Confirm that: - The user attempting to connect Salesforce **is a Salesforce Admin** - That Admin has permission to **approve uninstalled connected apps** Even some Salesforce Admins do **not** have this permission by default. --- **Resolution Steps** **Step 1: Grant Permission to Approve Uninstalled Connected Apps** Because the GovDash app is not yet installed, Salesforce may hide it unless the Admin has explicit permission. 1. In Salesforce, go to **Setup** 2. Search for **Permission Sets** 3. Click **New** - Name: `Approve Uninstalled Apps` - Click **Save** 4. Open the new Permission Set and go to **System Permissions** 5. Click **Edit** 6. Enable **Approve Uninstalled Connected Apps** 7. Click **Save** 8. Click **Manage Assignments** 9. Assign this permission set to yourself (the Admin) --- **Step 2: Trigger the App to Appear in Salesforce** Salesforce will not show the app until it has been “called” at least once. 1. Log in to **GovDash** 2. Make sure you are logged in as the **Salesforce Admin** who just received the new permission 3. Click **Connect Salesforce** > [!WARNING] > **Note:** You may still see an error on this first attempt. That’s expected. This step registers the app in Salesforce so it can be approved. In many cases, the connection will succeed immediately after this step. --- **Step 3 (If Needed): Install the App from OAuth Usage** If the connection still fails, or if other users will also need to connect, install the app directly in Salesforce. 1. In Salesforce, go to **Setup** 2. Navigate to **Connected Apps OAuth Usage** 3. Find the **GovDash** app in the list 4. Click **Install** 5. Confirm by clicking **Install** again --- **Step 4 (Recommended if performing Step 3): Update App Policies for Ongoing Access** To prevent future connection issues for other users: 1. In **Connected Apps OAuth Usage**, find the GovDash app 2. Click **Manage App Policies** 3. Set **Permitted Users** to: - **All users may self-authorize** 4. Under **IP Relaxation**, select: - **Relax IP restrictions** 5. Save your changes --- **When Are Steps 3 & 4 Required?** - If **only the Admin** is connecting GovDash, Steps 1–2 are often sufficient - If **other Salesforce users** will: - Connect GovDash - Run syncs - Authenticate the integration themselves then Steps 3 and 4 are strongly recommended --- **Still Having Trouble?** If you continue to see OAuth errors after completing these steps, please contact **GovDash Support** and let us know: - The exact error message - Whether the app appears in **Connected Apps OAuth Usage** - Whether the connecting user is a Salesforce Admin We’re happy to help get you connected. --- ### FAQ #### What permissions are required to connect GovDash with Salesforce? You must be both a Salesforce administrator and a GovDash administrator to grant the necessary permissions for the connection. #### How can I perform a one-time sync of Salesforce opportunities to GovDash? You can initiate a one-time sync by clicking the Sync Salesforce Opportunities button and mapping your phases from Salesforce to GovDash. #### What happens if the fields between GovDash and Salesforce do not match during a sync? If the fields do not match, GovDash will display 'null' in the corresponding field in your Pipeline opportunity Overview tab. #### Is it possible to automate the syncing of Salesforce opportunities with GovDash? Yes, you can enable automatic syncing of Salesforce opportunities by selecting the checkbox under the Phases heading after linking your phases. #### Can I customize the sync settings for Salesforce opportunities in GovDash? Yes, you can configure various sync settings, including Create Only Sync and Override Sync, on the Capture Settings page. #### What does an error message that starts with "Salesforce error:" mean? When Salesforce can't complete a request from GovDash, such as connecting your account or syncing your opportunities, GovDash shows the exact reason Salesforce gave, starting with **Salesforce error:**. For example, **Salesforce error: The REST API is not enabled for this Organization.** means your Salesforce organization doesn't currently allow API access, which GovDash needs in order to connect and sync. If an opportunity sync fails, the **Error syncing some or all Salesforce opportunities** notification can also show the reason Salesforce gave underneath it. Share the full message with your Salesforce administrator so they can resolve it in Salesforce, then try again. #### What does "REQUEST_LIMIT_EXCEEDED" mean? Salesforce limits how many API requests your organization can make in a rolling 24-hour period, and that limit is shared by every app connected to your Salesforce organization. When your organization reaches it, Salesforce turns away new requests and GovDash shows a message that includes **REQUEST_LIMIT_EXCEEDED** or **TotalRequests Limit exceeded**. GovDash won't keep retrying, so it doesn't use up more of your limit. If you've turned on automatic syncing, GovDash tries again on its next automatic sync and picks back up on its own once your organization has requests available again. If this keeps happening, ask your Salesforce administrator to review your organization's API usage in Salesforce or request a higher limit from Salesforce.