Business and Enterprise plans
OpenForms is phasing out support for version 1, 2, and 3 data connections.
As of December 2023, we will no longer offer customer support for these data connections, however they will keep working until we deactivate older version data connections in June 2024.
If you're building a new data connection today, make sure you're using version 4 or later. If your organization uses older version data connections, you will need to upgrade those to version 4 and update the middleware they access before June 2024.
Not sure how to get started? Contact support and we'll point you in the right direction.
Data connections are build-your-own integrations that send and receive data as respondents interact with forms. They can be used to validate, retrieve, or lodge data.
The flow of information can be one-way (such as as lodging response data at the completion of a form) or two-way (for example, when using a database to populate predictive search results).
Types of data connections
Data connections can be triggered the the beginning, middle, or end of a form. Each position corresponds to a different way of using data.
Not all types of data connections are available on older plans like Business and Pro.
| Type |
How they work |
|
Start-of-form connections
Not available on Pro plans
|
These connections are made as a form loads, before a respondent can view it. These kinds of data connections are used to pre-populate form fields with data available from the site hosting the form, or query lines in the URL.
For example, a form hosted on an Intranet page requiring a login may be able to draw information about a respondent from data tagged with externalID's on that page. This way, details such as the respondents name, position and so on can be pre-filled as the form loads. |
|
End-of-form connections
Not available on Pro plans
|
These connections are triggered when a respondent completes a form. These connections are typically used to lodge the information a respondent has provided in a CRM or DMS application, and provide a receipt on screen or via email.
|
|
Mid-form connections
Not available on Business or Pro plans
|
These data connections are used to send and receive data prior to the completion of a form.
Mid-form connections are typically two-way, and used to validate or retrieve data from a third-party service. However, they can also be simple one-way connections, such as an analytics cue.
Mid-form connections can, for example:
-
Use information from a respondent’s entries to query a database and pre-fill other areas of a form
-
Validate respondent data (such as their address, if they are organizing waste collection)
-
Send analytics data to help understand form engagement (such as at what point respondents are dropping out of forms)
-
Return information to make a text field a predictive search
|
Create a data connection
Before you begin
Before you start using data connections, you need to:
- Code middleware to translate between the data formats OpenForms and your external applications can use.
- Assign external IDs to the form fields you'd like to send and receive.
Code middleware
Data connections use a standard JSON format to send and receive information. Before you set up a data connection, you will need to create a middleware application to translate information between OpenForms and your external applications (such as a CRM or DMS).
Make sure your external applications have an API or some way for the middleware to connect to it. The middleware must also have a URL that OpenForms can send the JSON data to.
If you're a developer looking for more information about the JSON data that OpenForms can send and receive,have a look at our JSON object list and usage examples.
Assign external IDs
External IDs are used to tell middleware and, in turn, your external application, which fields you want to send and receive data from.
Each field you’d like use in a data connection needs an external ID assigned, and each field can only have one external ID.
To assign external IDs:
-
Open a form and select the gear icon next to a field.
-
In the Advanced tab, fill out the External ID field and and Set the ID. Fields can only have one ID.
-
Repeat this for every field you’d like to send or receive data for.
Create a data connection
Only admins can create data connections in OpenForms. If you’re not an admin, you can still add an existing connection to a form.
To create a data connection:
-
From the main menu, go to Connectors > Data connections. This is where you can create and manage any connections.
-
Select Add connection, or if you’d like to make changes to an existing connection, choose one from the list.
You can also import connections you've previously exported in other subscription of OpenForms. These will be added to your data connection list.
-
Whether you’re adding a connection or editing an existing connection, the data connection settings screen you'll see is exactly the same. Note that if you are editing an existing a connection, a widget in the right hand side of the settings screen will display how many forms are using the current connection. (Be aware making changes will affect these forms).
In this case, we’ll assume you’re adding a new connection.
-
Enter a Connection name and Connection description. It’s a good idea to write a comprehensive description so you have plenty of information when adding your data connection to forms.
-
Enter the URL of the middleware you’ve installed between OpenForms and your external application.
This is used to send and receive data. Ask your middleware developer if you’re not sure what URL to enter.
-
Choose your Connection type (‘send,’ or ‘send and receive’). This affects the field options available.
-
Specify the external IDs for the Form fields to send (for one way data connections) and the Form form fields to populate with the data received (for two way connections).
-
For data connections that send and receive data, specify how long to wait before timing out when waiting on return data.
-
Choose the Version of code to use. Different versions of data connections allow different information that can be sent and received, and how your middleware is coded. If you’re unsure, ask your developer or vendor what version of data connections your middleware is coded for.
When you choose a version of data connections, you’ll see the list of JSON objects that can be sent and received for that version.
- Use the Custom headers to send field to add any additional data or instructions you'd like to be sent to middleware when your data connection triggers.
This is a good place to add authentication data to ensure only your forms can access middleware, or any other additional data parameters you'd like to add.
-
Decide what happens if OpenForms can’t reach your external application.
-
Add you connection
Once your data connection has been added, you can insert it into forms, and update its details anytime by choosing it from the list in the data connections admin screen. You can also export it for use in other OpenForms subscriptions.
Add a data connection to a form
Add a start-of-form connection
Go to Forms and open a form, then go to Settings > Data connections. Under When the form, select which connections you want to trigger, choose Add and save your form. The connection will be triggered when the user loads the form.
If you're pre-filling form data for respondents, a start-of-form connection can use that data to populate additional fields.
Add an end-of-form connection
Go to Forms and open a form, then go to Settings > Data connections. Under When the form is submitted, select which connections you want to trigger, choose Add, and save your form. The connection will be triggered when the user clicks Submit.
End-of-form data connections trigger after form submission and cannot add additional data to that form with the exception of a reference ID or status.
Add a mid-form connection
- Go to Forms and open a form.
- Choose a field you want to add the connection to, and select the gear icon to open its settings.
- Open the Advanced tab and choose the connection you want in the Data connections field.
After you've selected a connection it will show you the list of external IDs that it will be sending and receiving so you know which ones you need to apply within your form. You can only apply a single connection to a field, but you can apply more to a section.
The connection will be triggered when the user clicks Continue within the section you added it to.
If your data connection is being used to return values to pre-fill fields, it helps if you put those fields in a different section. It would be confusing if someone entered their name and email and triggered a connection to pre-fill a field that they'd already passed.
Congratulations, you’ve set up a data connection. If you’re stuck, it might help you to look at our code examples for setting up middleware.