How do I connect a Droplet Dataset to a Form?

Modified on Mon, 19 Aug at 7:53 AM

The Datasets feature is only available with the Droplet Package or as an Add On

This guide will walk you through connecting a dataset to your form in Droplet. By the end, you’ll know the key differences between global and local datasets and how to efficiently use them to power your forms.

Connecting a Global Dataset

Step-by-Step Instructions

Grab your Dataset ID
Go to the Datasets tab in Droplet. If you’re creating a new dataset, follow the steps in our Creating and Updating Datasets guide. Once your dataset is ready and published, take note of its Dataset ID.

To find the Dataset ID, simply hover over your dataset’s name on the Datasets page until the ID appears. Clicking the ID will copy it to your clipboard for easy pasting!

You can also find the Dataset ID in the URL once you have opened your dataset. It's the six-character alphanumeric string tucked right in the center of the URL.

Access the Form Builder
Navigate to the Forms page in Droplet. Open the form you want to connect a dataset to, switch to the Code Editor using the switch in the upper-right corner, then click on the Dataset tab.

A Note on Using the Code Editor

We know the code editor can feel intimidating, especially if you’re new to it. But don’t worry — these steps are designed to be as straightforward as possible. Follow the examples closely, and you’ll be done in no time. Plus, we’re working on a visual way to connect forms with datasets to make this even easier in the future!

Define Your Dataset in the Form
In between the main pink curly braces, add the following code snippet:

"datasetName": { "datasetId": "datasetIDFromURL" }

Replace the pink datasetName text with a more descriptive name that you will use to reference this dataset in your form, like "schools" or "budgetCodes"

Replace the blue datasetIDFromURL text with the six-character alphanumeric Dataset ID you copied in Step 1.

⭐️

If you're still having a bit of trouble connecting your dataset using the code editor, we've built a generator for you to use.

Pointing to a Dataset Version

Sometimes, you might want your form to connect to a specific version of a published dataset, instead of always linking to the latest version. To do that, simply add a version property to your dataset connection like this:

"datasetName": { "datasetId": "datasetIDFromURL", "version": "v-#" }

Replace the purple # character with the number version you'd like to connect.

Using your Connected Dataset

Once your dataset is connected, you can use the name you assigned to it to reference the dataset throughout your form layout or workflow. This allows you to do things like populate Dropdown, Radio, or Checkbox options, calculate values dynamically in Computed components, or even assign workflow steps automatically based on your dataset.

Let's look at each of these uses:

To Populate Options

You can automatically fill components with data from your dataset by referencing its keys, or top-level items in your dataset. Think of keys like the parent folder of a folder structure.

For example, to populate a Dropdown with items from your dataset, select Logic from the Options property:

and under Options Logic, use this expression:

Object.keys(datasetName)

Replace the pink datasetName with your own specific name.

Example

Let’s say you have a dataset of schools named "schools". To populate a Dropdown with all the school names, you would use:

Object.keys(schools)

This pulls out all the school names from the dataset and lists them as options in the Dropdown. If your dataset has schools as the parent-level keys, each school name will show up as a choice for users.

Returning Values from Your Dataset Using Form Inputs

You can also use datasets to dynamically fill in data based on what users select or input as they complete the form.

This is the general pattern:

datasetName[componentID].key

Replace the pink datasetName with your own specific name. Replace componentID with the ID of a specific component on your form, like a dropdown menu or input field. Replace key with the item from your dataset you'd like to return.

Example

Imagine you have a dataset of schools, and each school entry includes a principal’s name.

Like this:

If a user selects a school in the form (say, from a Dropdown with the component ID "school"), you can automatically return that school’s principal using:

schools[school].principal

Here’s what happens: schools references your dataset, [school] pulls the selected school’s data (using the "school" component ID), and .principal returns the principal’s name for that school (since the key for that piece of data is labeled as "principal" in your dataset).

Dynamically Assigning Workflow Steps Using Datasets

Datasets can also help you automate who gets assigned to specific steps in a workflow. To assign a workflow step, Droplet needs an object with two key-value pairs: "name" and "email".

These pairs tell Droplet who should receive the submission.

Example

Let’s say you have a dataset of schools (called schools in your form's Dataset connections) where each school is a parent object, and each contains key-value pairs for the principal, including their name and email.

Like this:
Just as in the last example, let's also say that a dropdown menu component lists the schools in the dataset that a submitter can choose from; it's got the component ID "school".

If you want to assign a workflow step to the principal of the selected school, you would use:

schools[school]

This pulls the "name" and "email" of the selected school’s principal, allowing Droplet to assign the task directly to them. The parent keys in your dataset (like "schools") are the top-level items that group together related data, such as the principal’s contact info.

Pro Tip!
You may find it helpful to keep the Dataset open in another tab of your browser as you work or use the Form Debug tool to verify that you are correctly referencing data and that it is pulling into your form as you would expect.

With these tools at your disposal, you can make your forms much smarter and more responsive to user inputs. Whether you’re filling dropdown/checkbox/radio button options, calculating values, or automating workflow steps, connecting your global datasets opens up a world of possibilities in Droplet.