Set Up a Salesforce Data Destination

You can use Salesforce Data Destinations 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. to update or create records in Salesforce using data from your submitted forms. You can map data to any standard or custom object in your Salesforce org. You can then use this data for record keeping, reporting and analytics, and automated flows and processes.

This topic provides step-by-step instructions to configure different types of Salesforce Data Destinations, including:

• Salesforce Account

• Salesforce Case

• Salesforce Contact

• Salesforce Lead

• Salesforce Standard, Custom, or Big Object

Info:A Salesforce Apex REST The Salesforce Apex REST is a type of Salesforce Data Destination that enables TrueContext to interact with Salesforce by means of an Apex REST API endpoint. If using an Apex REST API endpoint, developers can write APEX code to send custom messages that pull specific data from submitted forms. 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. works differently than the others. The topic Set Up a Salesforce Apex REST Data Destination explains the differences and provides detailed configuration steps.

Available on the Advanced and Enterprise tiers:

Contents

• Set Up a Salesforce Data Destination
• Prerequisites
• Select a Salesforce Data Destination
• Configure the Name and other Destination Basics
• Configure filtering rules for Data Destination execution
• Map form data to Salesforce Fields
• Select or create a Salesforce Connection
• Send attachments and files to Salesforce
• Configure an Update Query to manage the creation of Salesforce records
• Store response outputs to create multiple records sequentially
• Create and save the new Data Destination
• Related topics

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.

3. Make sure that the TrueContext team has at least one Problem Contact Email Address. If the system fails to update records in a Data Destination, the Problem Contact Email Addresses get the error message and details.

4. Decide on the form data or metadata that you want to push to Salesforce fields. Note any question unique IDs and the DREL expressions needed to get that data from the submitted form.

   For example, if you want to push the answer from an “Email Address” question to a Salesforce Field, use the DREL Data Reference Expression Language (DREL) is used to get form data and metadata and add it to a string, such as dates, usernames, or answers to questions in forms. expression (%a[EmailAddress]), where EmailAddress is the question Unique ID A Unique ID refers to the specific identifier of a question, form page, form section, or Data Destination. Unique IDs are used as reference points when pulling data for conditional logic, Analytics projects, Data Destinations, and Documents..

5. If you want to configure a Salesforce Standard, Custom, or Big Object Data Destination, keep the API Name of the Salesforce Object ready for use.

   Info:The Salesforce topic Find API name describes how to find API names for Standard and Custom Objects in Salesforce Classic and Lightning experience.

6. If you want to configure a Repeatable Destination A Repeatable Destination is a TrueContext Data Destination that sends data from a Repeatable Section to a field-based, third-party system., note the Unique ID of the Repeatable Section A Repeatable Section is a subform that contains a set of related questions. The data captured is “repeating”, because the field user can complete the same subform more than once, which creates multiple entries. that you want to link to the destination.

Select a Salesforce Data Destination

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 Manage Forms > Data Destinations.

2. Select Create Data Destination.

3. From the Cloud Service Integration list, select the type of Salesforce Data Destination that you want to use.

   Type of Salesforce Data Destination	Description
   Salesforce Account Salesforce Case Salesforce Contact Salesforce Lead	These four types use preconfigured, standard Field Labels to make it easier to configure the Data Destinations in TrueContext. You can also map data to Salesforce Custom Fields.
   Salesforce Standard, Custom, or Big Object	This type doesn’t provide any preconfigured Field Labels. You must enter the API names of the Salesforce Object and Fields manually. Tip:The TrueContext Describe Salesforce Object functionality shows you a list of API names for the Salesforce Fields in your Object.
   Salesforce Apex REST	A Salesforce Apex REST Data Destination enables the interaction between TrueContext and a Salesforce or Apex Rest API endpoint. With a Salesforce Apex REST Data Destination, you can fully utilize the data collected in TrueContext for custom actions in your Salesforce org.

   Info:A Salesforce Apex REST Data Destination works differently than the others. The topic Set Up a Salesforce Apex REST Data Destination explains the differences and provides detailed configuration steps.

Configure the Name and other Destination Basics

On the Destination Basics tab, you can configure the name and other preferences:

• Auto-link newly created forms and specific document types to this destination.

• Disable the destination (to configure the destination for future use).

• Select the number of times the destination fails before the system sends a problem notification.

• Select the type of destination, either Regular or Repeatable (to send data from Repeatable Sections).

The following image shows how to configure the Destination Basics settings.

1. Name your Data Destination.

   The name helps you to identify and differentiate this Data Destination from other Data Destinations in your FormSpace.

2. Enter a Unique ID.

   The system automatically generates a Unique ID based on the name. You can change the system-generated Unique ID to any alphanumeric or special characters, but the ID must be unique within the FormSpace.

3. Do you want to set up this destination, but temporarily prevent sending submitted form data to it?

   • If yes, select the Disable this destination... option. This prevents the execution of the Data Destination, even if you link it to one or more forms. You can save the configuration and enable the destination later.

   • If no, clear the Disable this destination… option to enable this destination for immediate use.

4. The Auto-Link new forms… option automatically links new forms created or imported in the same FormSpace to the Data Destination. Do you want to auto-link forms?

   • If yes, select this option.

     Result: The system prompts you to auto-link documents. Go to step 5.

   • If no, clear this option, and then go to step 6.

5. The Auto-Link documents… option applies to auto-linked forms. This option saves you the effort of specifying a list of documents for each new form. Do you want to automatically link documents to this Data Destination?

   • If yes, select this option, and then select the documents to link.

   • If no, clear this option.

   Note:You can’t attach documents to a Repeatable Destination A Repeatable Destination is a TrueContext Data Destination that sends data from a Repeatable Section to a field-based, third-party system.. This prevents duplication of the same document across multiple records.

6. Do you want the Data Destination to loop through a Repeatable Section and create or update multiple records?

   • If yes, for any Salesforce Destination other than Apex REST, select the Use as a Repeatable Destination... option.

     Result: The system prompts you to enter a Repeatable Section Unique ID.

   • If no, select the Use a Regular Destination...option.

7. For Error Handling, from the Wait to send failure notification… list, select your preferred frequency.

   If a Data Destination fails to execute, the system continues the attempts to execute it on a regular schedule. The system sends emails to the Problem Contact Email Addresses based on the configured frequency.

   Tip: Most failures correct themselves and require no intervention.

Configure filtering rules for Data Destination execution

Filtering gives you greater control over which submitted forms are sent to your Data Destination. The Data Destination executes only when all conditions configured in the Filtering settings are met.

Keep the default settings or configure additional filter rules. Filter rules enable you to apply more conditions that determine whether the submitted form data gets sent to this specific Data Destination. You can apply filter rules to each of several Data Destinations to direct submitted forms to different destinations.

The following image shows how to configure the Filtering settings.

1. Select at least one Form Version State.

   If you want the Data Destination to receive data from…	Then select...
   previous form versions, not currently in use	Archived For example, you sent data from form submissions to an Email Data Destination. You now prefer to store all data in Salesforce instead. You can select Archived to send data from previous forms versions to Salesforce. Note:Make sure you link this Data Destination to the previous form versions: Manage Forms > FormName > Version History > Version > Form Outputs > Edit Form Outputs
   the latest form version, currently accessible to front-line workers	Active For example, you change a form to reflect the new product specifications. You can select Active to send data from only the latest form version to Salesforce.
   forms used for testing	Draft A draft form is a partially filled-out form saved on a device, or a preliminary version of a form that's been saved but not deployed in the Form Builder. For example, you dispatch a draft form to a few app users with Can Test permissions. You can select Draft to send data from the draft form to a Salesforce Sandbox. In this example, your Salesforce Connection must be configured as a Sandbox connection.

2. Select at least one Form Submission State.

   • Complete—execute the Data Destination when front-line workers submit complete forms.

   • Incomplete—execute the Data Destination when front-line workers submit incomplete TrueContext Teamwork-enabled forms (Enterprise tier only).

   • Dispatch The term "dispatch" refers to the act of sending a form to a mobile user or customer. Typically, a dispatched form includes some information pre-filled to give the recipient context for the work to be done. Dispatch can be manual or automated (using a Dispatch Data Destination or the TrueContext REST API). Declined—execute the Data Destination when you dispatch a prepopulated form to a Mobile App user and the app user declines the form.

3. In the Filter Rules section, you can apply conditions to execute the Data Destination based on form data and metadata. For example, you can create a rule to execute the destination only when a question has a response of “Pass”.

   • Do you want to execute the Data Destination only if the submitted data matches all of the rules?

     • If yes, select Match All. The destination executes if the submitted data matches all of the rules.

     • If no, select Match Any. The destination executes if the submitted form data matches at least one rule.

     Note:The Match Any/Match All option applies to the conditions defined in the Filter Rules section only. The Data Destination executes only when all conditions for Form Submission Filtering and Filter Rules are met.

   • Input Expression—enter a DREL expression to specify the form data or metadata to match.

   • Filter Expression—enter a regular expression to define the string that you want to match, for example, Pass.

4. For a Repeatable Destination, you can also create conditions to filter out rows in a Repeatable Section. For example, you can create a rule to execute only rows that have a response of “Pass” to a question.

   • Do you want to execute the Repeatable Section rows only if the submitted data matches all of the rules?

     • If yes, select Match All. The destination executes a row if the submitted data matches all of the rules.

     • If no, select Match Any. The destination executes a row if the submitted form data matches at least one rule.

   • Input Expression—enter a DREL expression to specify the form data or metadata to match.

   • Filter Expression—enter a regular expression to define the string that you want to match, for example, Pass.

Info:The topic Applying Filtering to Data Destinations describes in detail how to configure the Filtering settings.

Map form data to Salesforce Fields

For all Salesforce Data Destinations except Apex REST, the Salesforce Objects Fields or standard fields settings map submitted form data to Salesforce fields. The TrueContext system pushes the data referenced by a DREL expression to the mapped Salesforce Fields. Whether the system updates existing records or creates new records depends on the Update Query settings you configure.

1. What type of Salesforce Data Destination is this?

   • Salesforce Standard, Custom, or Big Object Data Destination—On the Salesforce Object Fields tab, enter the API Name of the object, and then go to step 2.

   • Salesforce Account, Case, Contact, or Lead—On the fields tab for the selected destination type, you can map submitted form data to standard Salesforce fields. Enter a DREL expression to reference the submitted form data that you want to push.

     For example:

     • Enter %a[UniqueID] to reference the answer to a question.

     • Enter %u[name] to reference the submitter's name.

     • Enter %d to reference the submission date.

     • Enter %t to reference the submission time.

     • You can combine a DREL expression with static text. In the expression Form Submitted by %u[name], “Form Submitted by” is static text.

     For standard objects, TrueContext provides a set of standard fields that you can use to map data from submitted forms. TrueContext uses these standard fields to automatically link records based on Salesforce lookups.

     For example, in the Salesforce Case destination, we use Account Name to find the AccountId that links the Case record to the Account record.

     

     Note:If more than one Salesforce record matches the specified value, TrueContext links the new or updated record to the most recently created matching record.

2. You can configure Custom Salesforce Fields for any standard or custom Salesforce Data Destination. To map data to custom fields, select Add to insert a row.

   Note:For Salesforce Account, Case, Contact, or Lead destinations, TrueContext uses standard fields to automatically link records based on Salesforce lookups. To avoid a “Duplicate Key” error:

   • Do not add custom field mappings for the following Salesforce fields:

     For the destination type...	Do not map to...
     Salesforce Account Destination	OwnerId ParentId
     Salesforce Case Destination	OwnerId ContactId AccountId
     Salesforce Contact Destination	OwnerId AccountId
     Salesforce Lead Destination	OwnerId

   • Do not map to the same Salesforce field more than once. For example, do not map to a standard field and then add a custom field mapping that points to the same Salesforce field.

   Result: You can enter the custom field data and a DREL expression.

   

3. Enter the Salesforce Field or API Name you want to push data to.

   Use Describe Object to find Salesforce API names

   When you map TrueContext data to fields in a Salesforce Data Destination, you might need to enter the Salesforce API names. The Describe Salesforce Object option retrieves a list of Fields and their API names from your Salesforce org.

   Tip:Select Describe Salesforce Object for help with API names. The Describe Salesforce Object option retrieves a list of Fields and their API names from your Salesforce org.

   

4. Enter the DREL Value Expression of the submitted form data or metadata that you want to push to a Salesforce Field.

   Do you want to push data to a Salesforce Geolocation field?

   • If no, go to the next section.

   • If yes, the following information shows you how to set up the DREL expression.

   Push Data to a Salesforce Geolocation Field

   The Salesforce Geolocation custom field is a compound field made up of latitude and longitude. To use a Data Destination to populate a Salesforce Geolocation field, you must include a DREL expression for each sub-field.

   • Reference the location where a user submitted a form:

     • %g[coordinates.latitude]

     • %g[coordinates.longitude]

   • Reference a location that a user submitted as the answer to a Geo location question:

     • %a[UniqueID][coordinates.latitude]

     • %a[UniqueID][coordinates.longitude]

   The following example shows a Data Destination configured to populate Geolocation fields based on the location where a user submitted a form.

   

   Make sure to use the correct Salesforce API name for the Geolocation sub-fields in your org. To find your org’s API names, select Describe Salesforce Object as shown in the following example.

   

   Info:To populate a Geolocation field with the location where a user submitted a form, you need to enable the Collect geo location setting on your form. The topic Set Up Form Properties describes how to configure the Geo location setting.

Select or create a Salesforce Connection

The Connection Configuration options available to you in this section vary depending on your account role settings and existing Salesforce 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..

Do you have a TrueContext Admin role?

• If yes, you can either select an existing Salesforce Connection or configure 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.

The following image shows how to configure the Connection settings.

Send attachments and files to Salesforce

You can choose to store attachments and files in a Files or Notes & Attachments related list. On the Attachments tab, choose the option that matches your current Salesforce version and configuration.

Attachments can include images, audio, or other files, and TrueContext Documents. Whether the attachments create new records or update existing records depends on the Update Query configuration.

The following image shows how to configure the Attachments settings.

1. Specify where in Salesforce you want to upload attachments, files, and documents. Depending on the configuration and version of your Salesforce org, select either Files related list or Notes & Attachments related list.

2. Do you need full-size images, audio, or other attachments and files from submitted forms?

   • If yes, in the Attachments to send field, enter a unique ID for each relevant question, separated by commas.

   • If no, leave the Attachments to send field empty. You can configure Documents and link the Documents to the Data Destination. TrueContext Documents contain inline images and links to files such as audio recordings and other attachments.

Store response outputs to create multiple records sequentially

Salesforce Data Destinations typically return a record ID to TrueContext. These responses enable you to make sequential requests, typically to create parent-child records.

On the Response Configuration tab, select either the Don’t store… or Store all… option as shown in the following example.

Tip:If you want to make this destination a parent of a child destination, select the option to store response outputs. When you configure the child destination, you can use the %o DREL Data Reference Expression Language (DREL) is used to get form data and metadata and add it to a string, such as dates, usernames, or answers to questions in forms. property to reference the stored output.

Create and save the new Data Destination

Once you configure all required settings, select Create.

Result: The system creates your Salesforce Data Destination in TrueContext and displays the Data Destination details page. You can now link the Data Destination to forms in the same FormSpace.

Tip: Test and troubleshoot a Salesforce Data Destination before you use the Data Destination in a live Salesforce environment.

Related topics

• Examples of Salesforce Data Destinations

• Set Up a Salesforce Apex REST Data Destination

• What is a Salesforce Data Destination?