Set Up a Salesforce Report or Query Data Source

This topic provides step-by-step instructions to configure a Salesforce Report or Salesforce Query Data Source Data sources, also known as "Lookups", are external sources of data that you upload or connect to TrueContext. You can reference this data in a form to populate answers or answer options. Data sources save typing, reduce errors, and make it easy to provide mobile users with only the relevant, most current data. in TrueContext. Once you create the Data Source, you can link it to forms to populate Dropdown, Multiselect, and Radio Button questions.

Available on the Advanced and Enterprise tiers:

Prerequisites

1. You must be either

   • a TrueContext Admin user or

   • a member of a FormSpace FormSpaces are where forms are stored and organized in the TrueContext Web Portal. A TrueContext Team may have multiple FormSpaces, depending on their needs. Admins can set FormSpace permissions to control which users have access to the forms in that FormSpace. group with Can Create permissions.

2. Either a Salesforce Connection already exists in your TrueContext FormSpace, or you are a TrueContext Admin user and can create a Salesforce Connection.

   In TrueContext, when you set up a Connection, you enter the account credentials for the third-party system. Once you save the Connection, it becomes available to TrueContext and other users for Data Source and Data Destination A Data Destination specifies where to send data from a submitted form. You can use Data Destinations to automate data sharing and storage, routing data to a specific service (such as email or cloud storage) in several different formats. setup. This means that other TrueContext users on your team can fetch and access data available to the third-party user account.

   Note:We recommend that you create a dedicated Integration User account for your third-party system and use that account to set up TrueContext Connections A Connection is an integration point that's used to link a TrueContext Data Source or Data Destination to an external service to import or export data. Data Destinations and Data Sources that share the same external service can also share the same Connection.. Set up the Integration User with specific permissions and limited access to the third-party system data. This ensures that TrueContext Admin users and users with “Can Create” permissions can only access the data that they need.

3. Make sure that the team has at least one Problem Contact Email Address. If the scheduled data fetch fails, the system sends an email with an error message and details to the Problem Contact Email Addresses.

4. To configure a Salesforce Report Data Source, set up a Salesforce Report that has

   • a tabular format

   • no grouped data, and

   • no more than 2000 rows.

   Note:Check that any filters on your Report return the records you need. If your filters don’t return any records, the Data Source fetch results in an error.

5. To use a Salesforce Query Data Source, test your query in the Developer Console Query Editor before you use the query in TrueContext.

Steps to set up a Salesforce Data Source

Select the type of Data Source

1. In the TrueContext Web Portal The TrueContext Web Portal is a web application used to manage security settings, forms, FormSpaces, other users, Data Sources, and Data Destinations., go to Forms & Integrations > Data Sources.

2. Select Create Data Source.

3. From the Cloud Service Integration list, select Salesforce Report or Salesforce Query.

   If you want to…	Then…
   Reference records from any reportable Salesforce Object using a report that has a tabular format does not have grouped data, and has up to 2000 rows.	Set up a Salesforce Report Data Source. Note:The data fetched by a Salesforce Report Data Source is truncated after 2000 rows.
   Use Salesforce Object Query Language (SOQL) to reference Salesforce records from any Salesforce Standard, Custom, or Big Objects, and with any number of rows.	Set up a Salesforce Query Data Source.

   Result: The system displays the page on which you configure the Data Source.

Name the Data Source and provide a description

The following image shows how to configure the Name settings.

1. Enter the Data Source Name.

   You might have multiple Data Sources Data sources, also known as "Lookups", are external sources of data that you upload or connect to TrueContext. You can reference this data in a form to populate answers or answer options. Data sources save typing, reduce errors, and make it easy to provide mobile users with only the relevant, most current data. in your TrueContext Web Portal. Follow best practices for easy identification:

   • Identify the Salesforce org.

   • Identify the Object.

   • Identify the Fields you intend to reference.

   For example, you might name your Data Source:

   ServiceMax_Account_Province_City_Street

2. Provide a Description (optional).

   Add a description that will help you identify the Data Source later, if you need to modify or delete it.

Note:The system displays Cells Allowed and Rows Allowed. based on your TrueContext tier. These values represent TrueContext size limits that optimize performance. The actual number of cells or rows that the system fetches from your Salesforce org also depends on the limits imposed by Salesforce.

Configure the data retrieval frequency and format options

The following image shows how to configure the Data Retrieval and Format settings.

1. Do you want to notify TrueContext Mobile App users after a data fetch?

   • If yes, select the Push updates... option. This ensures that your users have the most current data.

     Note:The TrueContext Mobile App users must enable notifications on their devices to receive updates.

   • If no, clear the Push updates... option.

2. Do you want to fetch data automatically?

   • If yes, select the Automatically fetch... option, and then set up the frequency and time zone. The system fetches the data at midnight in the selected timezone for all frequencies except hourly.

     Tip:Consider the fetch frequency and users’ experience when you decide whether to enable push notifications. For example, hourly notifications might distract users.

   • If no, clear the Automatically fetch... option. Remember that you must fetch the data manually when you want to update it.

3. Select Activate this schedule… to start the automatic fetches. When you want to pause the Fetch Schedule and switch to a manual fetch, edit the Data Source and clear the check box.

   Once you’ve created the Data Source, you can manually fetch new data at any time:
   Forms & Integrations > Data Sources > Data Source Name > Fetch New Data.

4. Keep the Trim whitespace… option selected to remove spaces, tabs, or other “whitespace” characters from all elements in the source data. This prevents formatting errors.

Configure the Salesforce Connection options

The configuration options depend on whether you selected a Salesforce Report or Salesforce Query Data Source.

The following image shows how to configure the Connection settings for a Salesforce Report Data Source.

The next image shows how to configure the Connection settings for a Salesforce Query Data Source.

SELECT Id, Name FROM Contact

1. Do you have a TrueContext Admin user role?

   • If yes, you can either select an existing Salesforce Connection or create a new one.

   • If no, you can only select an existing Salesforce Connection that’s configured for your current FormSpace. If the system displays No available connections, contact your company’s TrueContext administrator for help.

2. The configuration options depend on the type of Salesforce Data Source.

   If you want to configure a...	Then...
   Salesforce Report Data Source	Enter the Report ID. To find the Report ID, open your Salesforce Report. The URL in the browser's address bar includes the Report ID. https://na7.salesforce.com/01OE0010002k1NJ For example, the last part of this address, after the domain, is the Report ID. Note:Remember to check that any filters on your Report return the records you need. If your filters don’t return any records, the Data Source fetch results in an error.
   Salesforce Query Data Source	In the Query box, enter a SOQL expression. For example, to retrieve IDs and Names from your Contact Object, enter the following expression: SELECT Id, Name FROM Contact Result: The query fetches the following data. ID Name 4321 John Smith 1234 Jane Doe 2341 John Doe Tip:Test your query in the Developer Console Query Editor before you use the query in TrueContext. Your Salesforce org’s data model is inaccessible to external integrations, and TrueContext cannot troubleshoot SOQL issues. Select the type of Salesforce API based on the number of records. Do you have 10,000 or fewer data records in the Object? If yes, select Query. If no, select Bulk. Note: The Bulk API improves speed and efficiency but does not support all SOQL functions or field types. Refer to the Salesforce documentation for more details. TrueContext only supports the Salesforce Bulk API version 1.0.

3. Do you want to fetch data as soon as you create the Data Source?

   • If yes, select the Fill the Source Data immediately option.

   • If no, clear this option to fetch data as scheduled.

4. Select Create to save the Data Source.

   Result: The system creates your Salesforce Data Source in TrueContext. You can reference the Data Source in any form within the same FormSpace.

Related topics

• Decide on the Type of Salesforce Data Source

• What is a Salesforce Data Source?

• How a Salesforce Integration Works