Professional Business

Datasets are used in Gruntify forms to provide users with a pre-curated list of options that allow them to fill the form out more quickly. This comes with the added advantage of ensuring entered data is consistent and valid when compared to a free-form text field. Adding your organization-specific data to datasets allows you optimize field worker experience while also easing the development of custom reports and dashboards for executives.

How to use Datasets

Datasets can be used on either Dropdown controls or Multi Select controls in your forms. When you open the edit panel for one of these controls, you will see the ‘Data set’ field appear for you to select.

Open

Example dataset field for a dropdown

Inline Datasets

Inline datasets allow you to specify the options for a given dropdown or multi-select against that specific control. It makes sense to use these when workers will only have a few options to select from or when these options will only be used on a single control in the form.

To use an inline dataset, select “<Inline>” as the option for ‘Data Set’ and then fill out the options in the text area that appears. Each option should be on its own line - no commas or other separators are required. Once you are finished editing the inline dataset, click ‘Save’ at the bottom of the edit panel to save the control.

Open

Example of an inline dataset

Custom Datasets

Open

Datasets tab in the Form Builder Toolbar

Custom datasets are managed in the ‘Datasets’ tab of the Form builder toolbar. They allow you to import and define large, reusable datasets that can be referred to by multiple controls in the form. Another feature of custom datasets is the ability to represent cascading (aka multi-step) datasets across multiple dropdowns, which we will discuss later on in this article.

Importing Datasets

Custom datasets can be imported in either JSON or Simple Text format. This is useful if you already have a register or other record of all of the options you would like to make available, as you can easily drag and drop this data into a new dataset for use in your Gruntify form. See the section on dataset formats below for more details on how to structure the data for import.

Dataset Editor

You can also create and edit datasets in Simple Text format using the dataset editor. This will provide you with real-time feedback for any errors in your dataset if applicable. If you import a dataset in JSON format, it will still be displayed to you in Simple Text format in the editor, as it is automatically converted for you.

Using a Custom Dataset

Once you have imported and configured a custom dataset, you can use it in your form by selecting it as the option in the ‘Data Set’ field for any dropdown or multi-select controls. If you only see “<Inline>” as an option on this field, double check the ‘Datasets’ tab of the form builder toolbar to ensure that you have set-up your dataset correctly.

Open

Dataset Editor

Cascading Datasets

Cascading datasets are a powerful feature which allow you to span the selection of options in a dataset across multiple dropdown controls. This is perfect for when you have a very large dataset which could benefit from an initial ‘refining’ selection to reduce the number of options for a field user to search through. For example, if you have a dataset full of facilities at which a particular inspection could occur, it might make sense for the user to first select the “Region” and then select the specific facility from within that region.

To use a cascading dataset in your form, first add a dropdown control for each ‘level’ of the dataset. Then, select the dataset on the first dropdown control in the ‘Data Set’ field. For each subsequent dropdown, rather than selecting anything in the ‘Data Set’ field, set the ‘Parent Dropdown’ field instead. The ‘Parent Dropdown’ field should be set to be the level above the current dropdown’s position in the dataset.

Now if you look in the form preview, you should see that selecting an option for the first dropdown makes options appear in the second one, and so on. If you have any issues configuring cascading datasets in your form, feel free to raise a support ticket via our customer support portal and we will be happy to help you out.

Open

Example setup of a cascading dataset

Note on Custom Dataset Formats

Custom datasets are supported in two formats: JSON and Simple Text. Details of each format are below.

JSON Format

JSON formatted datasets work well for data that comes from another system. These can be imported to the ‘Datasets’ tab of the form builder toolbar by selecting a JSON file. For the import to succeed, the JSON must validate against the following schema:

Example

The below dataset will result in the example demonstrated in Cascading Datasets above.

Open

Simple Text Dataset Format

Simple Text is a Gruntify-specific data format that is designed to offer an easy way to manually create custom datasets while retaining the capability to represent cascading options. In Simple Text, each option is represented on a new line, where the line begins with at least one '+' character. The number of '+' characters at the beginning of the line represents the current level of the option. All top-level options will have one '+', while child options will sit beneath them with two '+' characters, and so on.

Simple Text datasets can either be imported from TXT files or created by hand in the dataset editor. You will see live feedback on the validity of your dataset as you edit it in Simple Text format.

Example

The below dataset will result in the example demonstrated in Cascading Datasets above.

Open

Datasets Video Example

The video tutorial below will explain how to create these datasets and how to apply them to dropdown and Multiselect controls.

Related articles