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

Use data connections to validate, retrieve or lodge data for your form

Business and Enterprise plans

Data connections allow information to pass between a form and a third-party service, such as a database. 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, and some positions (middle-form connections) are only available on an Enterprise plan. 

Type How they work

Start-of-form connections

Business and Enterprise 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

Business and Enterprise 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

Enterprise plan

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

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.

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 to do something with 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. 

    field gear.png

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

    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. From the main menu, go to Connectors > 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 import connections you've previously exported in other subscription of 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. (Be aware making changes will affect these forms).

    Data connections used

    In this case, we’ll assume you’re adding a new connection. 
  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.

    URL.png

    This is used to send and receive data. Ask your middleware developer if you’re not sure what URL to enter.
  6. Choose your Connection type (‘send,’ or ‘send and receive’). This affects the field options available.

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

    form fields send.png
  8. For data connections that send and receive data, specify how long to wait before timing out when waiting on return data.

  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.

    DCs.gif
    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 additional data parameters.
  11. Decide what happens if OpenForms can’t reach your external application.

    error.png
  12. 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.

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.

Add a mid-form connection

Enterprise plans

  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.

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?