The Connector Step allows you to exchange data between forms in your workflow and external sources.
To add this step to your workflow, click the "Add Step" button on your Map and then select to Add a Connector from the dropdown menu. You can also hover over the space in between Steps and the "+" icon will appear.
You can edit or delete a connector at any time by selecting it on the Map and opening the Properties Panel.
When you add a connector to a workflow, it will run separately from your individual forms and form level connectors. Form level connectors will not run in a workflow, and workflow level connectors will not run in forms. Additionally, any connectors you set up for a form in one workflow will not run in any other workflows that use the same form.
Please Note: If you change the form associated with the connector in your workflow, or change the type of connector in the Properties Panel, the connector configuration will be lost and it will need to be reconfigured. We strongly recommend finalizing the forms you will use and the order of your forms prior to finalizing your connectors to avoid needing to reconfigure.
Rules for Adding Connectors to Workflows
The position of the connector matters.
- Prefill connectors must be placed before a Form Step or another prefill connector.
- A submit connector can be placed anywhere in a workflow after the Start Workflow Step and will be tied to the form you set in the Configure tab.
- If a connector is tied to a form and then runs before the next redirect Step (either a redirect or another form), then it will notify respondents of any connector errors and will prevent submission if an error occurs. This is the same as the Form Submitted portion of the Connector Timeline seen at the form level.
- If a connector is tied to a form and runs after the next redirect Step (either a redirect or another form), then it will not notify respondents of any connector errors. This is the same as the After Form Submitted portion of the Connector Timeline seen at the form level.
Properties Panel Configuration
Adding a connector will automatically open the Properties Panel so that you can configure the Step. The Properties Panel for this Step contains the following tabs: Description, Configure, and Error Handling
You can delete any Step by opening the Properties Panel for the Step and clicking the red "Delete Step" button at the bottom.
This tab handles the details of the Step itself, such as the Step Name and Step Description.
This field allows you to give the Step a custom name, which can help you differentiate between your Steps. It has a default value of "Choose a Connector" until manually changed, or until a connector is selected in the Configure tab. If a connector is selected in the Configure tab, the default name will automatically change to match the connector.
You can use this field to add a description to your Step.
When you first open the Configure tab, you will see two fields, Select Form Response Action and Select Connector, followed by a Configure Connector button. These two fields will determine which form is collecting data for the connector, and then which connector will be run by this Step.
Select Form Response Action
This field contains a dropdown menu that lists:
- All Form Steps located above this Step in the Workflow Map
- A Form Step if it is located directly after this Step (for prefill connectors)
- A Form Step if this Step is located immediately above another prefill connector which is directly above the Form Step in question
You can also use the type-ahead input to narrow down the list of available Steps. The dropdown menu will list the Step names, not the names of the forms, so please keep this in mind when setting any custom Step names.
This field is disabled until the Form Step has been selected in the field above. It contains a dropdown menu that shows all available connectors for this Step. The list of connectors will be affected by the placement of the Step as well. For example, you will see a list of prefill connectors if this Step is directly above a Form Step.
The Configure Connector button will be disabled until a connector has been selected in the above field. Clicking on this button will open a connector configuration page where you can set up your connector. This page uses the same configuration settings as the form level connector configuration pages, so you can reference the related help documentation for each connector when configuring them.
Please note: Before clicking Configure Connector you must have pop-ups enabled in your browser. Otherwise you will not be able to access the correct configuration screen for your connector.
Error Handling Tab
With this tab, you can set a custom error message which will be displayed if an error occurs. The custom error message can be applied to any prefill, save, or on-submit connector.
For example, if an error occurs when sending form data to Salesforce on-submit then the error message from Salesforce is typically displayed to the respondent. However, these errors can appear confusing to form respondents. You can display a custom error message instead with the help of this tab.
You can enter plain text (no HTML) into this text area to create your custom error message. The custom error message will then be shown to the respondent if they encounter an error from the connector while responding to the form. The error will be styled according to the form theme's "Error Color" option.
You can also choose to display the connector generated error message below your custom error by checking the checkbox below the text area. This can be helpful when the generated error messages display useful information to the respondent, such as whether a credit card payment failed. This option is highly recommended for Payment Connectors.
- Salesforce Prefill (only before first form)
- Salesforce Marketing Cloud Prefill (only before first form)
- Google Sheets
- Salesforce Marketing Cloud
- Salesforce.org Elevate
Prefill Connectors and Workflow
To prefill a form within a workflow, you'll first need to configure the Form Step which will be prefilled. This is because a Connector Step shows a different list of available connectors based on which Form Step it is referring to. To show prefill connectors, you'll need to reference a Form Step after the Connector Step in the Workflow Path.
Prefill connectors can be run in one of two locations within Workflow:
- You can run a prefill connector before a Form Step.
- You can run a prefill connector at the start of a workflow.
Follow the steps in the sections below to prefill in one of these two locations.
Prefilling Within a Workflow
- Add a Form Step anywhere inside the workflow and configure the form which will be prefilled.
- Once the Form Step has been added and configured, hover over the space above the Step in your workflow. A "+" icon will appear to add a new Step.
Click on the "+" icon and then select to add a new Connector Step.
- Under "Select a Form Response", choose the form which you will be prefilling.
- Under "Select Connector", choose the prefill connector which you would like to run.
- Click Configure Connector and set up your prefill connector.
- Authenticate your prefill connector first. You can reference our help documentation if you need assistance authenticating a prefill connector.
- Next, set up your Lookup. Set the Salesforce field you'll be searching for on the left, then choose "Equals", and finally set the rightmost field to "a workflow parameter".
- For the parameter, choose simple, case-sensitive text which does not contain numbers or special characters. If you've set up a Salesforce Prefill connector before, this will function like an unsafe query parameter would.
- Finish setting up your prefill connector and Save before closing the configuration window.
- Now, you'll need to add your Workflow Parameters to the Step. In the Connector Properties Panel, open the Configure tab and scroll to the bottom. You'll see a section labeled Workflow Parameters.
- Click Add Parameter.
- On the left, fill the Parameter box with the parameter that you set for your prefill connector Lookup.
- On the right, you can use the Formula Editor in the Value box to create a formula or select a field from a previous form. This value will be your search value. The Lookup will search Salesforce for records where the parameter field matches the value. To learn more about prefilling with parameters, you can reference this help documentation.
- Add as many parameters as needed, and then Save your Workflow to complete the setup.
Prefill When Workflow Starts
To add a prefill connector to the beginning of your workflow, you'll need to first add your starting form. Once your first Form Step has been added and configured, you can hover over the space above the Step. A "+" icon will appear to add a new Step.
Click on the "+" icon and then select to add a new Connector Step.
When prefilling at the start of a workflow, you will need to append the prefill parameters to the end of your Workflow URL. You can follow the instructions here to build your prefilled link, while using the Workflow URL rather than the URL of the form.
When starting a Workflow with a prefill connector, it will use the traditional prefill parameters of formula, secure query, or unsafe query. Workflow parameters will not work at the beginning of a workflow because there aren't any preceding steps to pull the information from.
Once you have built your prefilled link, you can configure the prefill connector as usual. Please follow the steps in these help documents as you configure your connectors: