FORM Block


A FORM block is one of the most commonly used blocks in Checkbox, allowing you to use a variety of fields to customise a page that collects information from your user, which of course can be referenced and used later within an application.

 

Table of Contents

Form Block Basics

Dynamic Fields

User Picker

File Upload

Field Validation

Field Formatting

Default Values

Lookup Field

 

Form Block Basics

Available FORM Fields

You can add the following field types into your FORM:

Field Description Example Use Cases
Paragraph Displays text that requires no user input
  • Labels
  • Questions or prompts for user input
Text Input Prompts end user input that can contain a mix of alphabetical and numerical characters

Limitation: Any characters between "<" and ">" will not be shown when the text variable is referenced.
  • Collecting end user information (name, email etc)
Number Input Prompts end user input containing only numeric characters
  • Collecting financial information
Dropdown Prompts the end user to select an item from a drop-down list
  • Selecting 4 or more options (e.g. Titles - Mr, Ms, Mrs, Dr etc)
Radio Prompts the end user to select from multiple choice options
  • Selecting 2-4 options (e.g. Dog or Cat)
Date Prompts the end user to select a date from a calendar
  • Collecting date of birth of end user, contract start and end date etc
Slider

Prompts the end user to select a numerical input on a sliding scale

  • Collecting end user rating (e.g. 8/10)
Checkbox Prompts the end user to check or uncheck a checkbox. Variable is either ticked or not (i.e CBX1 == "TRUE" or CBX2 == "FALSE")
  • Single option to confirm a detail or not (check or unchecked)
File Upload Allows the end users to upload files. Uploaded files can also be viewed in the transcript. Learn more
  • Upload supporting documents
Document Upload Allows users to upload .docx files for use in the Document re view block.
  • Upload .docx files for document review.
User Picker Allows the end user to select a Team Member of the Project Team for any workflow actions. Learn more
  • Assigning next user in a workflow App

 

How to add, arrange and configure fields

  1. Click on your FORM block

  2. Click “OPEN FORM BUILDER”
    Data_Capture_Section_-_FORM_-_Google_Docs_2020-09-04_12-39-39.png

  3. [Optional] You can use the "Disable BACK button" toggle to prevent users from accessing any pages before this block. Turning this toggle ON will hide the "BACK" button on this page, as well as prevent the end-user from navigating back via the transcript. Any route backs returning to pages before this block will continue to work.

     

    Disabling the back button is useful in the following cases:

    1. You have an integration before this block, and you want to prevent users from accidentally triggering it twice
    2. You have email(s) before this block, and you want to prevent users from accidentally triggering it twice
    3. You're presenting some outcome to the end-user, and want to prevent them from returning to previous pages and changing their answers
    4. You've reached the end of the app, and would like to prevent the user from modifying their submissionblobid1.jpgAn example of the "Disable BACK button" toggle on a FORM block. This feature is also available on the List, Yes/No, Table, Transcript, Doc Review and End blocks.
  4. Drag in or click onto the desired field in the left panel. See video below

    Note: If you click to add a desired field from the left panel inside your FORM BUILDER, it will automatically be inserted at the bottom of all existing fields. To rearrange the order, simply drag and drop the fields into the desired order.

  5. Click on a field that has been added and set field labels and selection options in the Property Editor on the right panel. See video below

 

 

How to copy and paste FORM input fields


All fields in the FORM block can be copied and pasted into the same FORM block or across to other FORM blocks within the same App.

  1. Inside the FORM builder in Studio, right click onto a field and click “Copy”

    V1.18_Release_Notes___Wiki_-_Google_Docs_2020-08-14_10-43-13.png


  2. Right click onto the field again and click “Paste Above” or “Paste Below” depending on your preferred order to insert the copied field

    V1.18_Release_Notes___Wiki_-_Google_Docs_2020-08-14_10-44-22.png

Add Questions to FORM input fields

  1. Drag in or click onto the desired field in the left panel. For example, drag in an Text Input field

    Note: If you click to add a desired field from the left panel inside your FORM BUILDER, it will automatically be inserted at the bottom of all existing fields. To rearrange the order, simply drag and drop the fields into the desired order.

    _Draft__V1.21_Wiki_2020-12-23_17-31-43.png

  2. Click on a field that has been added and configure the details in the Property Editor on the right panel. For example, set the question to prompt the user for input in the Text Input field.

    _Draft__V1.21_Wiki_2020-12-23_17-32-56.png

 

Dynamic Fields

Why would you use dynamic fields?

Dynamic fields allow Authors to display Form elements only when a certain condition is met.This will then result in smart forms that change dynamically depending on the end users responses. This is done using conditions with operators and variable references.

For example, in the following video example, if the Counterparty is an Australian registered entity, an input field for the ABN will appear for the end user. Otherwise, the input field for Registered Company/Business number will appear.

How to create dynamic fields

  1. Click into a FORM block in the App Studio and click on “OPEN FORM BUILDER”

  2. Click onto an input field that has been added to the FORM that you want only to appear if a particular condition is met

    For example, in this case, we want to ensure that PARA13 and TXT14 only appear if the end user selects “Other” in the previous radio button choices (RAD12)

    Note: It is best practice to rename variables for easier recognition and referencing. Learn more about renaming variables. 

    Data_Capture_Section_-_FORM_-_Google_Docs_2020-09-04_12-51-56.png


  3. At the bottom of the right panel, click onto the “Conditional” toggle and define the Condition that must be true (i.e. the requirement that the end-user has to meet) for the selected question to appear. 

    Learn more about Conditions to understand how to write a requirement. Any variable in an App can be used to write conditions.

    Data_Capture_Section_-_FORM_-_Google_Docs_2020-09-04_12-52-44.png


    Note:
    Ensure that the Paragraph fields of the relevant input field also share the same condition.In the above example, steps 2-3 should be repeated for PARA13 to ensure that both PARA13 and TXT14 appear if the end user selects “Other” for RAD12.

 

Checkbox Field

 

 

 

User Picker

When would you use a User Picker?

A User Picker is a field in a FORM block that enables the end-user to select the name of a user in a Workflow Group or a Project Team. The User Picker variable can be used in various places including automated emails (Email block,Workflow emails), Rich Style Document Templates, E-Sign block or when assigning the next user in a Multi-User Assessment. Learn more.

Notes:

  • If the Project Team is a Global Project Team, users must have the "View User" permission level enabled in their role configuration at the account level to view other users in the User Picker dropdown. Learn more about user permissions in role configurations.
  • If the Project Team is a Global Project Team, the end-user will be able to select a user from a list of all users in the company-wide account from the User Picker dropdown.

 

User Picker Variables

Variable Example Description Used in

{{USER#}}

{{USER9}}

Returns an user ID that references a user Note: This variable does NOT need to be enclosed with double curly brackets (i.e. {{USER#}}) to be referenced in the Workflow block.
{{USER#.email}} {{USER9.email}} Shows the email of the user selected in the given User Picker
{{USER#.name}} {{USER9.name}} Shows the name of the user selected in the given User Picker

 

How to add a User Picker field

  1. On the left panel inside the Form Builder of a FORM block, click “User” to add a user variable drop-down

    V1.16_Relase_Notes___Email___Wiki_-_Google_Docs_2020-06-09_11-59-56.png


  2. Enter a caption for the variable field in the “Label Value” field.

    V1.16_Relase_Notes___Email___Wiki_-_Google_Docs_2020-06-09_12-03-17.png


  3. Using the drop-down menu, specify the workflow group the user can select the Project Team member from. “All Project Team Members” will be selected by default. Learn how to set up a workflow group.

    Note: When the “All Project Team Members” option is enabled for the User Picker for Global Project Teams, the end user is able to select from all users in the company-wide account.

    V1.16_Relase_Notes___Email___Wiki_-_Google_Docs_2020-06-09_12-03-58.png

 

How to reference a user picker variable

There are 3 user picker variables that can be referenced inside your App.

  1. The user selected in the user picker can be referenced using the following syntax:

    Variable

    Example

    {{USER#}}

    {{USER9}}


    This way of referencing user picker variables is commonly used when assigning Multi-User Assessments to the next user.

    Note: When referencing a user variable inside a Workflow block, do not include curly brackets. See screenshot below.

    User_PIcker_Article_-_Google_Docs_2020-09-04_12-12-25.png



  2. This way of referencing user picker variables commonly used in (but not limited to) E-Sign blocks to reference the name of the signatory or CC recipient(s). Learn more. See screenshot below.The name of the user can be referenced using the following syntax:

    Variable

    Example

    {{USER#.name}}

    {{USER12.name}}


    This way of referencing user picker variables commonly used in (but not limited to) E-Sign blocks to reference the email of the signatory or CC recipient(s). Learn more. See screenshot below.

    User_PIcker_Article_-_Google_Docs_2020-09-04_12-13-42.png


The email of the user can be referenced using the following syntax:

Variable

Example

{{USER#.email}}

{{USER12.email}}


This way of referencing user picker variables commonly used in (but not limited to) E-Sign blocks to reference the email of the signatory or CC recipient(s). Learn more. See screenshot below.

User_PIcker_Article_-_Google_Docs_2020-09-04_12-16-51.png



Learn more about the limitations of the user picker variables.

 

File Upload

SKIP AHEAD TO 
Why would you add a file upload field in your FORM?
Supported file types for each file type category:
How to insert a file upload field
How to download uploaded files from the transcript
How to reference FILE variables to view uploaded files
Limitations


Why would you add a file upload field in your FORM?

A file upload field allows an end user to upload documents as part of the Assessment.

Example use cases include (but not limited to):

  • An employee onboarding App that allows an employee to upload all their required documents
  • An incident recording App that allows users to upload photos/evidence while logging information for a claim

A triaging tool for legal review, where marketing/content teams can upload documents that are automatically assigned for review to the correct party using workflow.

 

Supported file types for each file type category:

Category File Type
Documents .doc, .docx, .pdf, .ppt, .pptx and .txt
Emails .msg, .edb, .eml
Spreadsheets .xlsx, .xls, .csv
Videos .webm, .mpg, .mp2, .mpeg, .mpe, .mpv, .ogg, .mp4, .m4p, .m4v, .avi, .wmv, .mov, .qt, .flv, .swf, .avchd
Archives .zip, .rar
Images

.jpg, .png, .jpeg, .svg

 

How to insert a file upload field

Follow the steps below to add a File Upload into a form in your application:

  1. In the relevant FORM page, drag in or click onto “File Upload” on the left panel

    _Draft__V1.21_Wiki_2020-12-23_17-53-25.png


  2. Edit the text box (i.e., rich text editor) on the right panel to add a question/instruction for the File Upload field

    _Draft__V1.21_Wiki_2020-12-23_17-53-59.png


  3. Using the checkbox, select the file types that can be uploaded by the end user


    Note:

    • By hovering your mouse over the checkbox, a tooltip will pop up showing the file types that are supported by each file type category.
    • The maximum file size of each file is 50MB
    • If only certain file types are chosen, it is best practice to update the question to include clear instructions that only certain file types can be uploaded. For example, if only “Documents” was checked, the question can be arranged to:

      “Please upload any relevant documents here:
      (Only .doc, .docx, .pdf, .ppt, .pptx, .txt files can be uploaded)”

      _Draft__V1.21_Wiki_2020-12-23_17-55-02.png


  4. [Optional] Check the "Custom" file type option to create a custom combination of files that the end user can upload and enter file types and separate them by a comma (e.g. .pdf, .mp4, .jpeg)

    _Draft__V1.21_Wiki_2020-12-23_17-57-40.png

 

How to download uploaded files from the transcript

Single file download:

An end-user can individually download uploaded files from the Transcript page with the following steps:

  1. Find the question on the Transcript page for which a file was uploaded
  2. Click the file icon. This will initiate a download

Learn more about Transcripts

Data_Capture_Section_-_FORM_-_Google_Docs_2020-09-04_13-01-21.png


Bulk file download:

An end-user can also download all the uploaded files in a .zip file from the Transcript with the following steps:

  1. In the Transcript page, click onto the “DOWNLOAD” drop down menu
  2. Select the option “UPLOADED FILES (.ZIP)”. This will initiate a download

    Data_Capture_Section_-_FORM_-_Google_Docs_2020-09-04_13-01-54.png

    Note: The below pop up window will appear once download has initiated:

    Data_Capture_Section_-_FORM_-_Google_Docs_2020-09-04_13-02-33.png

 


How to reference FILE variables to view uploaded files


FORM block:

FILE variables (e.g. FILE15) are the variables for file upload fields. It allows you to generate links that can be used to download and view the file(s) uploaded in an Assessment.

  1. Click onto a FORM block and click “OPEN FORM BUILDER” 
  2. Drag in or click onto a Paragraph field and reference a file upload field from another FORM block (e.g. {{FILE15}})

Note: Any variable including FILE variables cannot be referenced in the same FORM block with the file upload field and must always be referenced after file upload fields.

Data_Capture_Section_-_FORM_-_Google_Docs_2020-09-04_13-03-33.png

If you do this, all files uploaded in the file upload field (FILE15) will be referenced and appear as a list of individual download links in the middle of an Assessment. See below screenshot.

Note: A bullet point is automatically created with the generated link - this is especially useful when multiple files are uploaded.

Data_Capture_Section_-_FORM_-_Google_Docs_2020-09-04_13-04-10.png


Automated emails:

You can also reference FILE variables (e.g. {{FILE15}}) in the email bodies of EMAIL blocks or workflow emails.

Data_Capture_Section_-_FORM_-_Google_Docs_2020-09-04_13-05-11.png

 

 

Limitations

You CAN reference FILE variables in: You CANNOT reference FILE variables in:
  • YN blocks
  • LIST blocks
  • Paragraph fields in FORM blocks
  • EMAIL blocks or workflow emails
  • Block headers or descriptions
  • TABLE block cells
  • Rich Style Document Templates**
  • Document Builder documents

**Unless a Javascript Block is used.

 

Field Validation

SKIP AHEAD TO 
What is Field Validation?
Field Validation Options:
Text Input
Number Input
Date Input
File Upload
Slider


What is Field Validation?
 

Field/data validation allows users to validate end user inputs in FORM blocks. For example, a Text Input field in a FORM can be configured to validate and collect only email inputs to ensure that a valid email is entered by the end user.

Continue reading below for more field validation options.  

 

Field Validation Options:


Text Input
 

You can validate end user Text Inputs by: 

  1. Email - End users must enter aemail address in the Text Input field
  2. Character length - End users can only enter a specified number of characters set for the Text Input field (e.g. 15 characters)
  3. Regular expressions End user text inputs must match the regular expression pattern set by the Author

    What are regular expressions?
    Regular expressions (or RegEx) allows users to check series of characters for ‘matches’ in search patterns. In Checkbox, Authors can fully customise the String patterns expected from the end user to validate their input by using regular expressions. Custom error messages can also be created to help guide the user to enter the correct text input pattern. 

    For example:
    To prompt the user to enter their Tax File number (TFN) in the correct format with 8 or 9 digits separated by spaces (i.e. 123 456 789), use the following RegEx:

    (\d{8,9$})|(\d\d\d[ ]\d\d\d[ ]\d\d\d?)$

    And also add the following error message if the user input does not match the given format:

    "
    Please enter 8 or 9 digits and separate your TFN with a space for every 3 digits. E.g. 123 456 789.
    Learn more about and test your RegEx using the following resources: 

 

Number Input 

You can validate the number input from the end user by minimum or maximum values or both. 

  1. Only minimum value – If the user only limits the number input using a minimum value, the end user must enter a number that is above or equal to the minimum value
  2. Only maximum value – If the user only limits the number input using a maximum value, the end user must enter a number that is below or equal the maximum value
  3. Both minimum and maximum value - If the user limits the number input using both a minimum and maximum value, the end user must enter a number that is within the minimum and maximum range.

mceclip0.png


Date Input
 

 You can validate the date input from the end user by setting a date range by using either: 

  1. Date picker – The end user selects from a date range set by the Author of the App
  2. Date variables The end user selects from a date range that has been set dynamically based on their previous responses to the date fields in the Assessment. Enter the data variable WITHOUT double curly brackets ‘{{}}’. I.e. enter “DATE78” and NOT “{{DATE78}}”

v1.22_Release_Notes_and_Wiki_2021-02-11_19-19-37.png


File Upload
 

You can limit and validate the file type for the file that is uploaded by the user. End users can only upload files specified in the file type options set by the Author.

File option include:  

Category File Type
Documents .doc, .docx, .pdf, .ppt, .pptx and .txt
Emails .msg, .edb, .eml
Spreadsheets .xlsx, .xls, .csv
Videos .webm, .mpg, .mp2, .mpeg, .mpe, .mpv, .ogg, .mp4, .m4p, .m4v, .avi, .wmv, .mov, .qt, .flv, .swf, .avchd
Archives .zip, .rar
Images

.jpg, .png, .jpeg, .svg


Learn more about File Upload
 

Checkbox_2021-02-11_19-24-42.png



Slider
 

You can limit and validate the slider range by minimum and maximum values and set the slider counts to a specified number. 

  1. Slider range - The end user must select a number on the slider that is within the minimum and maximum range
  2. Slider steps – The end user can only slide across the slider by a specified number. For example, if the slider step is set to 2, the end user will be only be able to slide the numbers up or down by 2 (i.e. 2, 4, 6...10 etc) 

V1.19_Release_Wiki__1__2020-10-27_01-43-52.png

 

 

Field Formatting

When is Field Formatting used?

Field formatting allows for the customisation of the formatting for Number Input and Date fields.


Number Input field:

  1. Drag in or click onto a Number Input that has been added to the FORM

    Data_Capture_Section_-_FORM_-_Google_Docs_2020-09-04_13-14-19.png

  2. In the Property Editor on the right panel, customise the formatting by using the “Format Options” and view the changes under “Preview”

    Note: All format options are described at the bottom of this article.

    Data_Capture_Section_-_FORM_-_Google_Docs_2020-09-04_13-15-07.png


  3. (Optional) Enter a prefix (e.g. ‘US$’) if relevant to your question and view the changes under “Preview”. Up to 4 prefix characters can be used

    Note: This option is especially useful when collecting monetary values or currencies 

Number Input - Format Options:

Icon Option Description
Data_Capture_Section_-_FORM_-_Google_Docs_2020-09-04_13-18-14.png Percentage The number will be multiplied by 100 and a ‘%’ sign will be added at the end
Data_Capture_Section_-_FORM_-_Google_Docs_2020-09-04_13-18-45.png Digit Separation Every three digits will be separated by a comma

Data_Capture_Section_-_FORM_-_Google_Docs_2020-09-04_13-19-10.png

Decimal Right One more decimal place will be shown (up to four decimal places)

Data_Capture_Section_-_FORM_-_Google_Docs_2020-09-04_13-19-53.png

Decimal Left

One less decimal place will be shown

 

 

Default Values

SKIP AHEAD TO 
What is a default value?
Why should you use default values?
How to set up default values


What is a default value?

A default value is a value that is prefilled within user input fields by default in the FORM block. End users are still able to overwrite the default value in the FORM page. The user input fields that have an option to set default values include Text Inputs, Number Inputs, Drop-down, Radio Buttons, Checkbox, Slider and Date.

Note: By design, default values will only be functioning in FORM blocks. They will not be functioning in COMPs, routing, widgets etc.

 

Why should you use default values?

Default values allow for minimal data entry by end users as much as possible. For example, if the App requires to collect today's date, the default variable for the date variable can be set as today to avoid the end user from having to manually select the date.

 

How to set up default values

There are 2 ways you can use to set default values - set by value or by matching variables:

  1. Set by value

    Set by value options include:

    User Input Field Type

    Default Value Options
    Text Input Static text
    Number Input Static number
    Dropdown Select option created
    Radio Select option created
    Checkbox Checked or unchecked
    Slider Static number
    Date Check or uncheck "Set default value as today" option

    a) Add any user input field into the FORM block (e.g. Text Input)

    b) In the “Set Default Value” section in the Property Editor, select the "By value" option. This option should be selected by default

    _Draft__V1.21_Wiki_2020-12-23_14-53-55.png

    c) Since we are using a Text Input field in this example, enter a value in static text which you wish to prefill the input field by default
    _Draft__V1.21_Wiki_2020-12-23_14-55-03.png

  1. Set by matching variable

    a) Add any user input field into the FORM block (e.g. Text Input)

    b) In the “Set Default Value” section in the Property Editor, select the "To match variable" option

    _Draft__V1.21_Wiki_2020-12-23_14-56-01.png

    c) Using the dropdown, select a text variable in previous FORM blocks which you wish to prefill the Text Input field by default.

    _Draft__V1.21_Wiki_2020-12-23_14-56-43.png

    Note:
    You can only match variables of the same user input field type. I.e., Text Input fields can only match with other previous Text Input fields (I.e., text variables).

 

Lookup Field

Premium Checkbox Feature

Usage of this feature requires account access to Premium Checkbox features. For queries related to your licence agreement, ask your account administrator to contact your Checkbox Account Manager.

 

What is a Lookup Field?

A Lookup field is a field that allows one App to lookup and retrieve data from a Database or another App (i.e. a Flow App).

 

When would you use Lookup fields?

Lookup fields should be used when trying to automatically fill in the current App FORM fields based on a matching key variable.

Common use cases include:

Reference data examples (via the Lookup field):

  • Prefill commonly used data (e.g. Employee information, vendor information)
  • Audit - ongoing audit over a long period of time and revisit previous audit data on a regular basis
  • Human Resources – Looking up different employee details stored in a Database from an App for EOI, referrals, and performance reviews
  • Workflow – approvers or system owners to assign as an Approver

 

Lookup field glossary:

Source App: A "Source App" refers to the App you wish to retrieve data from. Source Apps can only ever be Apps within the same Solution (i.e. to retrieve data in one App from another App, they must both reside in the same Solution).

Database: A Database is an entity on Checkbox that stores data and acts as a single source of truth.

Key Variable: The variable that acts as the filter to retrieve the relevant data

 

How to configure a Lookup Field

Note: The following instructions will also assume that you already have a Database set up where you wish to retrieve data from

  1. Navigate to a FORM block in the App Studio of your chosen App

  2. Click "OPEN FORM BUILDER" to configure the FORM block

  3. From the left panel, drag in or click onto the "Lookup" field

  4. In the Property Editor (right panel), select from the radio options to lookup from either a "Database" or "Flow App" (i.e. an App). Skip to step 6 if you selected "Database"

  5. Use the initial "Lookup Source App" dropdown, and select the App you wish to retrieve data from

    Note: A "Source App" refers to the App you wish to retrieve data from. Source Apps can only ever be Apps within the same Solution (i.e. to retrieve data in one App from another App, they must both reside in the same Solution).
  6. Use the initial "Lookup Database" or "Lookup Source App" dropdown, and select the Database or App you wish to retrieve data from

    Note: Only Databases that have connected to/given permitted access to the respective Solution will be shown in this dropdown. Learn how to connect a Solution to a Database.
  7. In the "Match with Key Variable in Source App", select the variable in the Database or source App you wish to use as the filter to retrieve the rest of the related data

  8. In the "Map variables between this Form and Database (or Source App)" dropdown, select the variables you wish to pre-fill values in the current App with the variables from the Database or source App

    Note: The variables that are matched and mapped from the Source App must be exposed (variables from the Database are exposed by default). Also, the matching variables must have the same variable type (i.e. NUM variables in one App can only be matched by NUM variables from the other App).

  9. Click "+Add Variables" to create more mapped variables and repeat step 6 until satisfied

  10. In the "Columns to display in lookup result" dropdown, select the columns you wish to show when the lookup results show from the Lookup field when the user enters a matching key variable

  11. Click "+Add Columns" to add more columns to display when lookup results are shown

  12. Repeat step 8 - 11 until satisfied