Set Up a Salesforce Data Destination

You can use different types of Salesforce Data Destinations to update or create new records in Salesforce. 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 RESTClosed The Salesforce Apex REST is a type of Salesforce Data Destination that enables ProntoForms 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 DestinationClosed A Data Destination specifices 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.

Supported on the Advanced and Enterprise tiers:

Essentials
Advanced
Enterprise

Prerequisites

  1. You must be either

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

  3. Make sure that the ProntoForms team has a Problem Contact Email Address. If the system fails to update records in a Data Destination, the Problem Contact Email AddressClosed A Problem Contact Email Address is an email address an Admin defines in their team settings. If an issue occurs, such as network problems that cause a data destination to be inaccessible, ProntoForms sends an email to the Problem Contact Email Address. An Admin can override the team setting and specify a different email address at the FormSpace level. gets 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 DRELClosed 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 IDClosed 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 DestinationClosed A Repeatable Destination is a ProntoForms Data Destination that sends data from a Repeatable Section to a field-based, third-party system., note the Unique ID of the Repeatable Section that you want to link to the destination.

Select a Salesforce Data Destination

  1. In the ProntoForms Web PortalClosed The ProntoForms 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 ProntoForms. 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 ProntoForms 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 ProntoForms and a Salesforce or Apex Rest API endpoint. With a Salesforce Apex REST Data Destination, you can fully utilize the data collected in ProntoForms 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.

The Destination Basics tab is where you can canfigure the Data Destination name and other 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 DestinationClosed A Repeatable Destination is a ProntoForms 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 Address 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.

The Filtering tab enables you to set specific execution conditions for your Data Destination.

  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

    DraftClosed A draft form is a partially filled-out form saved to Drafts 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.

  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 ProntoForms 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—to map submitted form data to a Salesforce field, 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.

  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.

    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 ProntoForms 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 step.

    • 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.

    Include the Geo location DREL expressions for latitude and longitude under the Value Expression column.

    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.

    Select "Describe Salesforce Object" to open a list of API names related to your object.

    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 Configure Form Settings in the Form Builder describes how to configure the Geo location setting.

Note:Field mappings for data from repeatable sections is not currently supported.

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 ConnectionsClosed A Connection is an integration point that's used to link a ProntoForms Data Source or Data Destination to an external service in order 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 ProntoForms 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 ProntoForms administrator for help.

The following image shows how to configure the Connection settings.

Shows how to configure the connections tab to select an existing connection or create new connection

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 ProntoForms 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.

Shows how to configure the attachments tab to select a location and attachments to send.

  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. ProntoForms Documents contain inline images and links to files such as audio recordings and other attachments.

Configure an Update Query to manage the creation of Salesforce records

How an Update Query works

By default, Salesforce Data Destinations create a new record for each submitted form. For example, a Data Destination can create new account records in a Salesforce Account object. If the account record already exists, however, you can update it rather than create a duplicate.

To update a Salesforce record, you must set up matching criteria so that the system can find the correct record in Salesforce. The term matching criteria refers to the mapping between Salesforce fields and the values from a submitted form.

For example, you can use a Salesforce Data Source to populate a read-only question in a form. In this example, the question has a unique identifier of CaseID. When the front-line worker submits the form, the system updates the Salesforce record that matches the CaseID value from the submitted form.

The matching critera map the CaseID question value in the submitted form to the Id field in the Salesforce object.

Tip:You can use a ProntoForms Data Destination to update a Salesforce path with data from a submitted form. When a ProntoForms mobile user submits the form, the Salesforce path shows progression.

Steps to configure an Update Query

The following image shows how to configure the Update Query settings for a Salesforce Data Destination.

Shows how to configure the Update Query tab to insert conditions for updating existing records in Salesforce

  1. For Match Handling, select an Update Handling option as described in the following table.

    If you select... Then ProntoForms...
    Never update, always create new (default)

    Does not search for matching records and always creates new records.

    This option requires fewer API calls, which improves overall performance.

    Update if exists, otherwise create new

    Searches for matching records:

    • If a match is found, the system updates an existing record.

    • If no match is found, the system creates a new record.

    Update if exists, do not create new

    Searches for matching records:

    • If a match is found, the system updates an existing record.

    • If no match is found, the system does not create a new record.

    Result: If you select one of the update options, the system displays the additional configuration options described in steps 2 and 3.

  2. Specify the behavior when the system finds multiple matches.

    Tip:When ProntoForms searches for matching records in Salesforce, the results are sorted by creation date, with the newest records first. You can change the default sort order with an “order by” statement in a Custom SOQL Query.

    If you select... Then ProntoForms...
    Update the first record found (default)

    Updates the newest matching record.

    Update the last record found

    Updates the oldest matching record.

    Create a new record

    Preserves the existing matching records and creates a new one.

  3. Select the type of query that you want to build to find matching Salesforce records.

    Do you have a custom Salesforce UI?

    • If yes, you might want to manually build a Custom SOQL query. You can also control the sort order with this type of query, as shown in the following example:

      Select FirstName, LastName, CompanyName from Contact where FirstName= '%a[FormFieldFirstName]' and CompanyName = '%a[FormFieldCompanyName]' and LastName = '%a[FormFieldLastName]' order by CreatedDate DESC
      Note:
      • You must put single quotation marks around the DREL Value Expressions.

      • Date/Time values in the form must match the format required by Salesforce:

        • Date only: YYYY-MM-DD

        • Date and Time: YYYY-MM-DD:mm:ss+hh:mm

      • You can use a SOQL query when you need matching criteria on related objects, not just the object associated with the Data Destination.

    • If no, you can use the default Query Builder to match Salesforce Field or API Names to DREL Value Expressions. Go to step 4.

  4. Select a Query Operator to define the matching behavior.

    • And matches Salesforce records for all specified form data values.

    • Or matches Salesforce records for at least one of the specified form data values.

Store response outputs to create multiple records sequentially

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

Info:The topic Use Response Data Handling to Store Data Received from a Third-Party System explains how these work and provides sample use cases.

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

Shows how to configure the response configuration tab to store data returned by Salesforce for later use

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 DRELClosed 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 ProntoForms 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