We noticed that JavaScript is disabled in your browser. We suggest enabling it for a better experience.
We noticed you're using an older version of Internet Explorer. We suggest you update to the latest version for a better experience.
Skip to main content
  • Home
  • Developers
  • Use Data Connections to Validate, Retrieve, or Lodge Data for Forms
Print

Use Data Connections to Validate, Retrieve, or Lodge Data for Forms

Team and Enterprise plans

OpenForms has phased out support for version 1, 2, and 3 data connections. 

As of July 2024, we no longer offer these data connections. 

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, they will no longer work and you will need to upgrade those to version 4. 

Not sure how to update? Contact support and we'll point you in the right direction. 
Data connections send and receive data as respondents interact with forms. They can be used to validate, retrieve, or lodge data externally.

The flow of information can be one-way, such as as lodging response data at the completion of a form, or two-way, like when using a database to populate predictive search results.

Before you create your data connection, you must:

  1. Understand what type of data connection you want to create
  2. Code middleware to translate between the data formats OpenForms and your external applications can use
  3. Assign external IDs to the form fields you'd like to send and receive

Types of Data Connections

Data connections can be triggered at the beginning, middle, or end of a form. Each position corresponds to a different way of using data.

Type How they work

Start-of-form connections

 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 external IDs on that page. This way, details such as the respondent's name or position can be pre-filled as the form loads.  

End-of-form connections

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

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

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.

65.png

 

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.

Developers can look through our JSON object list and usage examples for more information about JSON data that OpenForms can send and receive.

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:

  1. Open a form and select the gear icon next to a field. 

    open field settings with the gear icon

  2. In the Advanced tab, fill out the External ID field and Set the ID. Fields can only have one ID.

    add external id field

  3. 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:

  1. Go to Integrations > Data connections. This is where you can create and manage any connections.

  2. Select Add connection, or if you’d like to make changes to an existing connection, choose one from the list. 

     data connections add connection button highlighted

    You can also select Import connection, to import one you've previously exported from OpenForms. These will be added to your data connection list. 

  3. 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. Any changes to the data connection will affect these forms.

    Data connections used

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

  5. Enter the URL of the middleware you’ve installed between OpenForms and your external application; the URL must begin with https://.

    URL.png

    This is used to send and receive data. Ask your middleware developer if you’re not sure what URL to enter.

  6. Select your Connection type. You can choose to Send data only or Send and receive data, and this affects the field options available.

  7. Specify the external IDs for the Form fields to send.

  8. If you selected Send and receive data as your Connection type, you will also need to enter an external ID in the Form fields to populate with the data received field, and specify How long to wait before timing out.
    form fields send.png

  9. 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. 
  10. 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. 
    header.png
    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.

  11. Decide what happens if OpenForms can’t reach your external application. You can choose to Allow the user to continue or Prevent the user from continuing, and you can enter an Error message to display.
    error.png

  12. Add your 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 Start-of-form Connection

  1. Go to Forms and open a form.
  2. Go to Settings > Integrations > Data connections.
  3. Under When the form loads, use the Add a data connection field to select which connections you want to trigger.
  4. Select Save data connections, then Save and Publish your form, and 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

  1. Go to Forms and open a form.
  2. Go to Settings > Integrations > Data connections.
  3. Under When the form is submitted, use the Add a data connection field to select which connections you want to trigger.
  4. Select Save data connections, then Save and Publish 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

  1. Go to Forms and open a form.
  2. Choose a field you want to add the connection to, and select the gear icon to open its settings.
  3. Open the Advanced tab and choose the connection you want in the Data connections field.
  4. Select Apply.

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.

Was this helpful?

Related topics