---
title: Set Up a Salesforce Query Data Source
description: This topic explains how to set up a Salesforce Object Query Language Data Source. It also covers how to enable the on-demand option, so your field technicians always get the most up-to-date data.
source_file: Features/DataSources/OnDemandDataSources/SalesforceSOQLWithOnDemand.htm
---

# Set Up a Salesforce Query Data Source

A **Salesforce Query Data** Source is used to fetch data directly from Salesforce objects—like Accounts, Contacts, or Work Orders—into your TrueContext forms. You write a SOQL query to choose which records and fields to retrieve. This topic explains how to set up a **Salesforce Object Query Language** Data Source. It also covers how to enable the on-demand option, so your field technicians always get the most up-to-date data.

Available as an add-on for the Intelligent and Elite tiers:

—Digital

Add-onIntelligent

Add-onElite

[?](https://truecontext.com/pricing/)

---

## Step-by-Step: Set up a Salesforce Query Data Source

### Prerequisites

- You must have the right permissions: Admin or **Can Create** in your FormSpace.
- Your team needs a [Salesforce connection](../../../RevisedSalesforceIntegration/5StepsSetUpSalesforceConnection.md) set up in TrueContext.

---

### Create the Data Source

1. In the TrueContext web portal, go to **Forms & Integrations**>**Data Sources**.
2. Select **Create Data Source**.
3. Choose **Salesforce Query** as the type.
4. Give the Data Source a clear name, such as Salesforce Work Orders.
5. Add a description to help others know what this Data Source does.
6. A Salesforce Query Data Source supports the [on-demand option](IntroToOnDemand.md#How), which enables dynamic data retrieval based on information provided in a form.

   Do you want the Mobile App to fetch the latest data from Salesforce using the on-demand option?
   - If *yes*, select the **Enable on-demand data retrieval…** option, and then go to the section [Set Up the Salesforce Connection](#Set4).

     Once you create the Data Source, you can’t change your selection for the on-demand option.
   - If *no*, go to the section [Set up the fetch options (scheduled)](#Set2).

---

### Set up the fetch options (scheduled)

1. Select **Push updates to devices after a fetch** to notify Mobile App users when new data is fetched.

   Your Mobile App users must [enable push notifications](../../../Published/217499008_EnablePushNotificationsMobileDevice.md) to receive them. Remember that too many push notifications might distract your field technicians.
2. Do you want to fetch data automatically?
   - If *yes*, select **Automatically fetch new data…**, and then choose the fetch frequency and time zone.

     The topic [Data Sources Overview: How the system schedules Data Source fetches](../../../Published/217500328DataSourcesOverview.md#How) describes these settings in more detail.

     If you need to fetch data more often than once per hour, you can use an [API call to fetch Data Source contents](https://live.prontoforms.com/api-docs#tag/Data-Sources/paths/~1formspaces~1{formSpaceId}~1sources~1{sourceId}~1fetch/post).
   - If *no*, you can [manually fetch new data](../../../BuildAndManageForms/DataSources/217500348CreateManageDataSources.md#To) when you need to. Go to step 4.
3. Do you want to start the schedule now?
   - If *yes*, select **Activate this schedule**.
   - If *no*, go to step 4.
4. To fetch the data as soon as you save the setup, select **Fill the Source Data immediately**.

---

### Set Up the Salesforce Connection

1. On the **Connection** tab, select an existing Salesforce connection or [create a new one](../../../RevisedSalesforceIntegration/5StepsSetUpSalesforceConnection.md).

   If you need a new connection and you’re not an Admin user, ask your TrueContext team admin to create the connection.
2. Write and test your SOQL Query.

   The Salesforce developer documentation includes guides and resources to help you understand, use, and build SOQL queries:

   - Use the [Salesforce Object Query Language (SOQL) Reference Guide](https://developer.salesforce.com/docs/atlas.en-us.soql_sosl.meta/soql_sosl/sforce_api_calls_soql.htm).
   - Test your query in the [Developer Console Query Editor](https://help.salesforce.com/s/articleView?id=platform.code_dev_console_tab_query_editor.htm&type=5) before you add the query to the Data Source.
3. In the **Query** field, write your SOQL query. For example:

   ```
   SELECT Name, Account__r.Name, Calibration_Due_Date__c, Equipment_Name__c, Equipment_Name__r.Name, Model__c FROM Calibration_List__c
   ```
4. Did you select the on-demand data option?
   - If *no*, go to step 7.
   - If *yes,* add a `WHERE` clause that includes from one to ten parameters. These parameters are used to filter data based on values provided in a form. For example:

     ```
     SELECT NT_Work_Order__r.name, name, task_type__c, result__c

     FROM Work_Order_Task__c

     WHERE NT_Work_Order__r.name = '{{WorkOrderName}}'

     ORDER BY task_type__c
     ```

     In this example, the `{{WorkOrderName}}` parameter will be mapped to a question in a form. The value provided will be used to fetch a subset of data from Salesforce.

     - Format parameter names as strings in double braces. Use only letters, numbers, hyphens, or underscores.
     - Your query must include at least one and no more than 10 parameters. Each parameter name in the SOQL query must be 255 characters or fewer.
     - The field type in Salesforce dictates whether quotes are needed in the query.
       - Many Salesforce unique identifiers are alphanumeric and *should* have straight quotes.
       - If the field in Salesforce is a **Number** type field, then you should specify the parameter *without* quotes.
5. Complete a **Test Fetch** to ensure that query returns the expected results.

   Select **Test Fetch**, enter actual values for all query parameters, and then select **Fetch**.

   A successful fetch displays the first ten matching rows.

   The **Test Fetch** must return at least one result before you can save the Data Source. If the **Test Fetch** fails, adjust your query or parameter values and try again.
6. If your test returns more than 10 rows, and you want to see all of the matching rows, select **Download CSV**.

   The system downloads a CSV file to your device. Open the file to see all of the data returned by the query.

   The maximum is 1000 rows for an On-Demand Data Source.
7. Select the type of **Salesforce API** based on the number of records.

   Do you have 10,000 or fewer data records in the Salesforce object?
   - If *yes*, select **Query**.
   - If *no*, select **Bulk**.

     The **Bulk** API improves speed and efficiency but does *not* support all SOQL functions or field types. [Refer to the Salesforce documentation](https://developer.salesforce.com/docs/atlas.en-us.242.0.api_asynch.meta/api_asynch/api_asynch_introduction_bulk_api.htm) for more details. TrueContext only supports the Salesforce**Bulk** API version 1.0.
8. Select **Create** to save the new Data Source.

   If you change the Data Source query or connection after you save an On-Demand Data Source, you must complete another **Test Fetch**.
9. Use the Data Source in a form.

   The topic [Use Data Sources in Forms](../../../Published/217500828_ReferenceDatasourcesInForms.md) provides detailed steps to set up your form, including steps for using an On-Demand Data Source.

---

## SOQL query structure for On-Demand Data Sources

| Clause | What it does | Example |
| --- | --- | --- |
| SELECT | Defines the fields to return | SELECT NT_Work_Order__r.name, name, task_type__c, result__c |
| FROM | Specifies which Salesforce object to query | FROM Work_Order_Task__c |
| WHERE | Filters results based on the parameters | WHERE NT_Work_Order__r.name = '{{WorkOrderName}}' |

- You can use up to 10 parameters in your WHERE clause.
- Each parameter—like `{{WorkOrderName}}`—must be mapped to a question in your form.
- You can select up to 10 fields to return.

---

## Best Practices

- Use clear names and descriptions for your Data Sources.
- Test your SOQL queries in Salesforce first.
- Limit the number of fields and rows to what you really need.
- Use on-demand for data that changes often or is too large to fit [standard size limits](../../../GetStarted/DataSourceSizeLimits.md#Why).

../../../markdown/Features/DataSources/OnDemandDataSources/SalesforceSOQLWithOnDemand.md