Introduction

HelloID Dynamic Forms allow you to gather more information about a user's Self Service product request, and use that information later in the request process. This article explains how the form designer works and provides reference material for form elements and their properties.

Visual form designer

1. Form Name
   The name of the newly created form.
2. Search
   Search and filter the list of available form elements.
3. Form Elements
   A list of all available form elements, each of which is detailed later in this article.
4. Form Workspace
   This is the area in which you will place and configure your form's elements. To add a element here, either select its plus (+) icon, or drag it onto the workspace.
5. Multistep Form
   Enable this toggle to create a multi-page form. A multi-page form is useful to take user input as arguments on one page, and then display the results via a data source-populated element on a subsequent page. 
6. Switch to JSON Editor
   The JSON editor allows you to view and modify the code that defines the form. If you have a form that you want to use as a starting template, you can copy its code here, to paste into a new form.

As an example, we've created a basic form that asks for a user's first name, last name, and email address. All elements are required.

After placing a form element in your workspace, edit its properties by selecting its pencil icon. Alternatively, remove a element by selecting its trashcan icon.

In the screenshot below, you can see the edit dialog of a text input element. 

When multiple elements are present, reorder them by dragging them up or down with the drag control.

JSON editor

Use the advanced JSON editor to examine and edit the code that defines your form, and to validate test input values.

Select the Switch to editor button to open it:

The JSON editor has the following components:

1. Form Definition
   The JSON code that defines the form. You can edit the form's properties directly from here if necessary, but it is recommended to use the visual designer. You can also copy the JSON code by clicking the Copy button. Paste the JSON into a new form to create a duplicate form, without having to manually add all of the elements again.
2. Form Preview
   A live preview of the form. Any changes made to the form definition are automatically displayed here. You may also enter form values and select the Submit button to test validation and form results.
3. Form Result
   A representation of the data submitted through the form. Updated after you select the Submit button in the Form Preview area. Useful for verifying that the entered data was put into the expected variables. You can copy the JSON code by clicking the Copy button. 

Form element reference

 Form elements come in three types:

• Display elements
  Simple HTML tags that display static content, such as headers and blocks of text. Useful for presenting information to the end user who is filling out the form. Their properties generally only include what text is to be displayed, and if their value should be shown on the form summary.
• Input elements
  Form elements into which end users may enter values, either by typing or selecting from a list. The properties of input elements are much more numerous and flexible than those of display elements. Each input element has validation options to ensure entered values conform to expected inputs (e.g., a phone number format), as well as a form key (i.e., variable name) that can be used to reference the entered value later in the request process.
• Container elements
  Help visually organize forms, by grouping together other form elements.

Listed below is a description, screenshot, and property list for all available element types. 

Make component dependent support indicates whether the component can be set to depend on another value.

Display elements

Header

An <h3> tag with static text of your choosing.

Text

A paragraph of static text with the contents of your choosing.

Input elements

Checkbox Input

A single check box. You may choose whether to display a classic check box, or a toggle switch.

Confirm Password Input

A password input and a confirmation input. Their values must match before the form may be submitted.

Date & Time

A date and time selector. The date is in day, month, year format.

The output is always UTC. This element is still a Date & Time element even if it is configured to only display a date.

Drop Down

A drop down list. Its values are statically defined during form creation, unless you specify a data source.

Dual List

A dual list control. Allows you to move items from one list to another, such as "available groups" and "assigned groups".

Email Input

An email address input.

Grid

A grid with selectable rows based on data from a data source.

Export results

When a Grid element is used on an in-production form, users can select the Export button to download a .csv file with the grid's current results. Only currently displayed fields (limited by the current search term, etc.) are included.

Markdown

A paragraph of markdown text, where you may add various types of formatting and external links.

Advanced font styling (e.g., color) and embedded images are not supported.

Multi Checkbox

A group of check boxes. Allows end users to select zero or more options from the group.

Multiselect

A multiselect element, where users can select any number of given values. Its values are statically defined during form creation. 

Number Input

A numeric input.

Password Input

A single password input. No confirmation is necessary.

Radio

A set of radio buttons. Its values are statically defined during form creation.

Text Area

A text area.

Text Input

A single line text input.

Time

A time selector. 

User Selector

A user selection drop down, where the end user can select another HelloID user in your organization. This can be used to perform actions on the selected user, or pass along that user's information as part of the form submission. A user scope filter is used to specify in-scope users.

Container elements

Form Row

A container which holds up to three other elements. It displays these elements horizontally, on the same row.

When you create a Form Row element, it contains two Checkbox Input elements as default placeholders:

You can delete them as needed, and/or drag-and-drop other form elements into the Form Row. For example, in the following screenshot, the second Checkbox Input has been deleted, and a Drop Down has been added in its place:

By previewing the form, we see the elements are horizontally aligned on the same row:

Form element property reference

• Label
  The name of the form element. Displayed above the element on the form.
• Use switch (Checkbox and Multi Checkbox only)
  Show toggles instead of traditional check boxes. Does not change functionality.
• Scope (User Selector only)
  Determines which users are available to be selected. Select the Managed Users button to populate the selector with the requesting user's managed users. Or, select the Custom filter button to specify users by matching user attribute values.
  
• Placeholder
  Grayed-out text shown inside the empty form element, to prompt the end user on what value to enter. A placeholder value is not a prefilled value. It is merely a UI hint, and will not be submitted along with the form if left unchanged. Compare with prefilled value.
• Use data source
  Populate the element with data from a data source instead of specifying it in the form editor.
  
  • Use value from other field
    Only applies to input keys configured in task or PowerShell data sources. Passes another field's value to the data source as an argument, and then populates the field with the result.
  • Display field
    The data source property whose values will populate the element's fields.
  • Value field
    The data source property whose values will uniquely identify the element's fields.
  • Text field
    The data source property whose values will label the element's fields.
  • Default selection
    Sets a pre-selected value for the element, when the element is connected to a data source. Read more about the Default Selection option.
    • Selection property
      The data source property that determines which item will be pre-selected.
  • Checked status field (Checkbox Input only)
    The data source property whose values will determine whether the check box is prefilled. Boolean true values will set the box to checked; anything else is interpreted as false.
  • Value property (Date & Time and Time only)
    The data source property whose value will determine the element's prefilled value. The data source should contain a single property whose value is in the format emitted by the JavaScript Date.toJSON() method: 1975-08-19T23:15:30.000Z
  • Source of all options (Dual List only)
    The data source property whose values will determine the left side column options, which the end user chooses from.
  • Source for pre-filled options (Dual List only)
    The data source property whose values will determine which options are prefilled in the right side column.
    
• Checked by default (Checkbox Input only)
  Determines whether the check box is prefilled. If this option is disabled, then the default value is null when programmatically interacting with the check box. If the form user checks and unchecks the box then the value will become false. Evaluate a checkbox using = $true or != $true.
• Enable filter (Dual List only)
  Show a search box above each of the two lists, so the user can filter by entering a value.
  
• Dual list options definition (Dual List only)
  Statically define the left side column options. The definition should be a JSON array of objects, each with two properties: a unique identifier and a label. The names of these two properties, respectively, must then be entered into the Key and Display fields under Mapping properties.
• Use search filter (Grid only)
  Show a search box above the grid, so the user can filter by entering a value.
• Prefilled value
  A default value entered in the field. If left unchanged, will be submitted as if the user had entered it. Compare with placeholder.
• Column mapping (Grid only)
  Choose how the data source's properties will be mapped onto the grid's columns. Select the Get columns from datasource button to automatically suggest a mapping.
  
  • Column header
    The text which will be used as the column's label.
  • Field
    The data source property to map onto the column.
• Validation options
  Prevents the form from being submitted if the entered values do not conform to the specified validation options.
  
  • Required
    The form cannot be submitted unless all fields in the element have been filled out.
  • Minimum length
    For elements with text input, specifies a minimum character length.
  • Maximum length
    For elements with text input, specifies a maximum character length.
  • Pattern match
    For elements with text input, specifies a Regex pattern to match.
• Form key
  A variable name which can be used later in the Self Service request process to reference the element's fields and values.
• Read only
  Available only for Text Input and Password Input elements. Prevents the user from editing the field. The main use case is to let you generate a value in a delegated form using a data source (e.g., a generated password), show it to the user, and then use the value as input into the delegated form's PowerShell task (on its Task tab, via the $form variable) without the user editing the value. A standard Text field doesn't work for this use case, because it doesn't have a Form Key and therefore can't be accessed in the form's PowerShell task.
• Summary visibility
  The last page an end user sees when filling out a form is a summary page, which displays all information entered into the form. If you want to hide an element (or just its value) from the summary page, select the appropriate option from this drop down.
• Height (Grid only)
  The height of the grid, in pixels.
• Text area height (Text Area only)
  The height of the text area, in pixels.
  
• Conditional visibility
  Only show the element if the specified condition is met.
  
  • Field is visible when
    The condition which determines if the element is shown. The condition is based on the current state of other elements on the same form. It is only possible to create a single condition.
• Make component dependent
  Make the element's value mirror the value of another element in the form, or a URL query parameter. See How to work with dependent form elements.
  
  • Choose what to depend on
    Whether to depend on either another form element, or on a URL query parameter.
    
    • Choose your component to depend on
      The form element to depend on, if Choose what to depend on is set to other element.
      
      • Depend on a specific property
        The specific property of the form element to depend on, if the chosen element outputs an object.
    • Query parameter to depend on
      The URL query parameter to depend on, if Choose what to depend on is set to URL query parameter.
• Selectable values
  Statically define values for the element's fields. Applies only when a data source is not being used.
  
  • Use custom labels
    Specify a separate label for each field, rather than using the field's value itself.
    
• Mapping properties (Dual List only)
  Specifies the data source properties to use for the options' unique identifiers and labels.
  
  • Key
    The data source property to use to uniquely identify the options.
  • Display
    The data source property to use to label the options.