How do I connect a Droplet Dataset to a Form?

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

The Datasets tab of the Droplet form builder is where you will connect any Global Datasets you've created or define Local Datasets to be used in only this form. 

There are two types of datasets

• Global Datasets
• Local Datasets

Global Datasets

Global Datasets are defined in your organization's Datasets tab and can be used across forms. You should use a Global Dataset to manage data outside of your forms - such as a list of locations with the associated administrators and their email addresses. This allows you to update the Dataset when a change is required and not need to update all forms that reference this data.

First, you must create a Dataset from the Datasets tab to use Global Datasets. You can read this article about creating and updating Datasets to learn more. 

Once your Dataset is created and published, you can define it in the form. To define the dataset, navigate to your Forms page then open the form builder and switch to the Dataset tab from the More dropdown. 

Now you will see the code editor for the Dataset object. It uses JSON to define all Datasets this form will use. For the Datasets you've set up to use across your forms, you will add code like the snippet below to reference the Dataset you made and give it a name to use in the form layout. Name the dataset something to help you remember what data it contains. For example, a descriptive name for the datasets with locations and the associated administrators might be  "administratorsByLocation".

Using the Optional version number:

"nameOfGlobalDataset": { "datasetId": "DatasetIDFromURL", "version": "v-#" }

Leaving out the Optional version number (commonly used):

"nameOfGlobalDataset": { "datasetId": "DatasetIDFromURL" }

To find the Dataset ID, you will hover over the name of your dataset and the ID will pop-up. You will then need to highlight and copy that ID. 

Dataset Versioning

If the data in this form should be unlocked, or should update with every new version of the Dataset, you can leave off the "version" part of the Dataset definition. Not including a version in the definition, will leave the dataset unlocked in this form so it will always reference the current published version of this Dataset. 

If data in this form should be locked, or should not change with new versions of the Dataset, you can lock the data in this form by including the version number. To update the data in a version-locked form, you would publish a new dataset, create a new draft of this form and update the version number and then publish the form. 

Local Datasets

Local datasets are datasets that are defined in a form and can only be referenced or updated in that form. 

If a form has many fields that require a "Yes"/"No" selection from the user or if you would like to use a Dropdown to select the user's state of residence, you can define this in a local dataset and save yourself a bit of typing. 

 "local": {
    "yesNo": {
      "values": ["Yes", "No"]
    },
    "states": {
      "value": [
        "AK",
        "AL",
        "AR",
        "AS",
        "AZ",
        "CA",
        "CO",
        "CT",
        "DC",
        "DE",
         "FL",
        "GA",
        "GU",
        "HI",
        "IA",
        "ID",
        "IL",
        "IN",
        "KS",
        "KY",
        "LA",
        "MA",
        "MD",
        "ME",
        "MI",
        "MN",
        "MO",
        "MS",
        "MT",
        "NC",
        "ND",
        "NE",
        "NH",
        "NJ",
        "NM",
         "NV",
        "NY",
        "OH",
        "OK",
        "OR",
        "PA",
        "PR",
        "RI",
        "SC",
        "SD",
        "TN",
        "TX",
        "UT",
        "VA",
        "VI",
        "VT",
        "WA",
        "WI",
        "WV",
        "WY"
      ]
    }
  }

"nameOfLocalDataset": { "values": [] or {} }

Local Datasets don't have versioning outside of the current form version. If you need to make edits to the Local Dataset, you can create a new draft of the form, make any changes necessary, and then publish a new form version. 

Using your Dataset

Once your Dataset is connected here in the Datasets tab, you can use the name you gave it to reference the dataset in the layout or in the workflow. You could call the dataset to help populate the options in a Dropdown, Radio, or Checkbox component, use it in a formula for a Computed component, or use it to determine dynamic workflow assignments. 

If you would like to use your keys from your data to populate a Dropdown component, you may want to use a code snippet like the one below. This code snippet pulls only the keys out of the dataset and sorts them in alphabetical or numerical order. 

Object.keys(datasetName).sort()

If you would like to reference your dataset in a formula, you can use other component IDs to return the information you need. You may use a code snippet that uses something like this:

datasetName[idName].key

or

administratorsByLocation[location].name

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.