How do I connect a Droplet Dataset to a Form?

Modified on Tue, 2 Sep at 7:36 AM

The Datasets feature is only available with the Droplet Package or as an Add-On. Contact Droplet if you do not have Datasets in your left-side navigation menu.

This guide will walk you through connecting a dataset to your form in Droplet.

Connecting a Dataset

Step-by-Step Instructions

In the form editor, open the three-dot menu in the upper-right corner and select Manage Datasets.

Select one or more datasets to connect to this form. If you have many datasets, you can search for the right ones at the top.

Click Apply. You can now use your connected datasets in your form.

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, add a version property to your dataset connection.

Open the Code Builder (three-dot menu → Code Builder → Datasets tab), find the relevant dataset, and add a version property, like in the example below:

"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 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 the dataset's name. Find this name in the Manage Datasets modal: the name is in parentheses next to the connected dataset.

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.