JSON Forms

On this page:

User Guide

In this guide, we introduce how to use JSON Forms in Itential Automation Platform (IAP) by providing a walk-through of how to navigate and use the Form Builder application. There are two main components to the JSON Forms application that enable management of forms, a form collection and form builder page. These forms can be used throughout IAP. At a high level, this is achieved by the JSON Forms builder providing the functionality to generate a JSON Schema representation of a form via a drag and drop user interface.

Collection Page

All forms created are displayed in a card grid on the collection page, including previously created forms.

Collection Page

The following actions can be taken from the collection page:

  • Create a form.
  • Delete an existing form.
  • Navigate to the Form Builder to edit an existing form.
  • Export/import forms to and from JSON files.
  • Sort forms inside the card grid.

Create a New Form

  1. Click the plus icon Plus Button to open the Create New Form card.
  2. Enter a form name (required) and a description (optional).
  3. Click Save.

Create New Form

Delete an Existing Form

Using the Card Menu

  • Click the stacked dots icon Card Menu to display more options inside of a card.
  • Click Delete to delete the form.

Note: You can also use the top menu bar within Form Builder.

Card Menu Delete

Using Multi-Select

  • Click the select icon Card Select to mark the form as selected.
  • Click the delete icon Delete Selected to delete all selected forms.
  • Click the unselect icon Unselect all to unselect all selected forms.

Using Sidebar Navigation

  • From the sidebar, click any form in the list to navigate to the Form Builder for that particular form.
  • The cards icon (upper-right corner) will navigate you to the Home page.

Sidebar

Using the Card Menu

  • Click the stacked dots icon Card Menu to display more options inside of a card.
  • Click Edit to make changes to a form.

Card Menu Edit

Export Forms to JSON Files

Using Multi-Select

  • Click the select icon Card Select to mark the form as selected.
  • Click the stacked dots icon Card Menu in the toolbar to display import/export options.
  • Click the Export menu option to export all selected forms to JSON files.

Using the Card Menu

  • Click the stacked dots icon Card Menu to display more options inside of a card.
  • Click the Export menu option to download a JSON file representation of the form.

Card Menu Export

Import Forms from JSON Files

  • Click the stacked dots icon Card Menu in the toolbar to display import/export options.
  • Click the Import menu option to import forms from previously exported forms. One or more forms can be imported at a time.

Clone a Form

Using the Card Menu

  • Click the stacked dots icon Card Menu to display more options inside of a card.
  • Click the Clone menu option to create a copy of the form.

Note: You can also use the top menu bar within Form Builder.

Card Menu Clone

Preview a Form

Using the Card Menu

  • Click the stacked dots icon Card Menu to display more options inside of a card.
  • Click the Preview menu option to show a preview of the form.

Card Menu Preview

Sort Forms

  • Click the sort icon Sort Button in the toolbar to modify the sort options.
  • Use the dropdown to change the property the sort is performed on.
  • Use the Ascending and Descending radio buttons to change the sort order.

Sort Options

Working with Form Builder

In Form Builder it is possible to change the structure and element composition of previously created forms. From the Form Builder screen you can update a form name, add new form elements, change existing form elements, restructure a form through drag and drop reordering, and inspect different types of form previews.

Form Builder

The following section provides an overview of how to build and edit a JSON form.

Available Elements

The element bin is on the right side of the form builder. There you can find all available elements that can be added to a form.

Available Elements

Layout Elements

Layout elements are not used to directly provide an input field, but rather to group elements or provide unique data structures. There are two types of Layout Elements:

  • Containers store form elements to build logical groupings of related form elements. These sub-elements are rendered vertically.
  • Tables store form elements to build repeatable groupings of related form elements. Each element added to a table becomes a column in the table. Once the form is rendered, tables allow rows to be added that are made up of these sub-elements for capturing data.

Form Elements

Form elements are used to provide fields that capture values on input. There are five types of Form Elements:

  • Text Input — Used to capture short string values.
  • Text Area — Used to capture long string values.
  • Number Input — Used to capture integer or decimal values.
  • Checkbox — Used to capture boolean values.
  • Dropdown — Used to capture strings from a set of options.

View and Update Form Details

Update the Form Name or Description

Click the gear icon Form Details Icon in the top bar of the Form Builder to open form details. This drawer displays information about who created the form and when, along with who last updated the form and when. From the form details screen, the form name and description can be changed.

Form Details

Using the Form Builder Canvas

The Form Builder canvas is where the form is built by dragging elements onto the "Drop elements here" zone. As the form is being built, it can be previewed and the generated form schemas can be inspected.

Form Builder Canvas

Add Elements to a Form

Layout and form elements can be added to a form by dragging the available elements from the element bin onto the form canvas. For example, to add a text field to a form, drag-and-drop the element labeled Text Input.

Add Elements

Change an Element's properties

Each form element can be edited by clicking its gear icon Form Element Edit. This will open the available properties for editing a form element. Below is a list of available properties currently supported for each form element. To update the name of a layout element, edit the text field next to the Container/Table label.

Element Properties
Text Field Label, Placeholder, Description, Required, Pattern Validation, Dynamic Validation
Text Area Label, Placeholder, Description, Required, Pattern Validation, Dynamic Validation
Number Field Label, Placeholder, Description, Required, Dynamic Validation
Checkbox Label, Description, Checked
Dropdown Label, Placeholder, Description, Required, Static Options, Dynamic Options, Pattern Validation, Dynamic Validation
Property Description
Label The name of the field.
Placeholder A user prompt or hint usually displayed inside of the input field before data is entered.
Description A short description of the field. This displays below the field label.
Static Options A list of static values to be used as options for dropdowns.
Dynamic Options Used to retrieve a list of dynamic values through an HTTP request by providing a specific configuration to setup data binding via a request and a value mapping.
Checked When set to yes, this defaults the value of a checkbox to true.
Required A value input is required.
Pattern Validation A regular expression used to validate an input value.
Dynamic Validation Used to validate an input value through an HTTP request by providing a specific configuration to setup a data binding via a request and a value mapping.
Adding Dropdown Options

There are two methods of adding dropdown options, static and dynamic.

Static Options

To add static options for a dropdown, set the options type to static. Click the + Option button to add items to the draggable list and use the input field to change the value of the dropdown option. Use the drag handle icon Drag Handle to reorganize the list items via drag and drop. Use the delete item icon Delete Item to remove an item from the dropdown options.

Editor Static Options

Dynamic Options

To utilize dynamic options for a dropdown, the following fields have to be configured.

Property Description
Method The request method.
Request Body The request body in the form of JSON.
Base URL The request scheme/protocol + authority + optional port.
API Route The request path + optional query.
Source Property A property on the response that contains the array to use as the dropdown options.
Property Key A property that exists for each of the objects within the array selected on the source property that will become the value of the dropdown options.

The fields configure the HTTP request and the data mapping that will occur when the form is rendered. Follow these steps to configure the request:

  1. Select a Method. If POST is selected, then the Request Body field requires input.
  2. Input the Base URL.
  3. Input the API Route.
  4. Hit the play icon button (in Step 1: Request Configuration) to view the response from the request.
  5. Select the Source Property.
  6. Select the Property Key.
  7. Hit the play icon button (in Step 2: Source To Target Mapping) to see a preview of the values that will populate as the dropdown's options.

Editor Dynamic Options

Adding Validation

There are two methods of adding validation, pattern and dynamic. These can be used together or independently. Both can be added by clicking the + Validation button on field editors, where this option is enabled.

Editor Validation

Pattern Validation

To add a pattern validation input a regular expression into the text field labeled Pattern.

Dynamic Validation

To utilize dynamic validation, the following fields have to be configured.

Property Description
Method The request method.
Request Body The request body in the form of JSON.
Base URL The request scheme/protocol + authority + optional port.
API Route The request path + optional query.
Source Property A property on the response that contains boolean value telling if the field value is valid. Currently, only truthy properties are support, meaning isValid will work, but isInvalid will not.
Dynamic Request Body Property A property on the request body.
Error Message The error message for when the input value is not valid.

The fields configure the HTTP request and the data mapping that will occur when the form is rendered. Follow these steps to configure the request:

  1. Select POST Method and input the Request Body. The Request Body is a mock body for when the request is actually made on during form field input.
  2. Input the Base URL.
  3. Input the API Route.
  4. Hit the play icon button (in Step 1: Request Configuration) to see the response from the request.
  5. Select the Source Property.
  6. Hit the play icon button (in Step 2: Source To Target Mapping) to see a preview of the boolean value that determines a valid input value.
  7. Select the Dynamic Request Body Property (in Step 3: Validation Configuration) to pick which request body property will have its value replaced by the input value being validated.
  8. Input the Error Message that is displayed when the input value is invalid.

Reorder Elements

Any form element can be reordered by dragging it from its original location to a new location and dropping it.

Delete Elements

Click the trash can button Trash Button (top-right corner) to delete an element from the form.

Save Form Changes

Click the Save button to capture any changes made to a form.

Preview a Form

As a form is being built, the form can be previewed by clicking the eye icon Form Preview Icon in the footer of the Form Builder canvas card.

Form Preview

Inspect the Generated Schemas

To evaluate the underlying data structures that are generated as a form is built, click the code icon button Schema Preview Icon in the footer of the Form Builder canvas card. This displays the JSON Schema, UI Schema, Binding Schema and Validation Schema for the form.

Schema Preview