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. To enable comparison across timezones, the date input uses and captures the end user's timezone. The end user's timezone is used when the date variable is displayed. e.g. if the end user who saved the date variable was in AU it will be in AU time regardless of where it is displayed	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”
   
   
   
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 submissionAn 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”
   
   
   
   
   
2. Right click onto the field again and click “Paste Above” or “Paste Below” depending on your preferred order to insert the copied field
   
   
   

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.
   
   
   
   
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.
   
   

 

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. 
   
   
   
   
   
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.
   
   
   

   
   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	Multi-user Assessment Workflow 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	E-Sign block Automated Emails FORM Rich Style Document Templates TABLE See more
{{USER#.name}}	{{USER9.name}}	Shows the name of the user selected in the given User Picker	E-Sign block Automated Emails FORM Rich Style Document Templates TABLE See more

 

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
   
   
   
   
   
2. Enter a caption for the variable field in the “Label Value” field.
   
   
   
   
   
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.
   
   
   
   

 

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.
   
   
   
   
   
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.
   
   
   
   
   

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.




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
   
   

   
   
   
   

2. Edit the text box (i.e., rich text editor) on the right panel to add a question/instruction for the File Upload field
   
   
   
   
   
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)”
     
     
     
     
     

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)
   
   

 

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

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
   
   
   

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

   

 

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.

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.

Automated emails:

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

 

 

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 an email 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 a 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: 

• Regex Expressions
• RegEx Testing Tool
   

 

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.

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}}”

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 

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) 

 

 

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
   
   
   
   
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.
   
   
   
   
   
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
	Percentage	The number will be multiplied by 100 and a ‘%’ sign will be added at the end
	Digit Separation	Every three digits will be separated by a comma
	Decimal Right	One more decimal place will be shown (up to four decimal places)
	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
   
   
   
   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
   
   
   

2. 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
   
   
   
   c) Using the dropdown, select a text variable in previous FORM blocks which you wish to prefill the Text Input field by default.
   
   
   
   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

 

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

 

WAIT Feature

Checkbox FORM blocks also support WAIT functionality. This allows authors to pause and then auto-progress workflows when certain conditions are met.

WAIT functionality can be enabled by checking the "Enable Wait Block" toggle in your FORM block config.

 

We currently support 3 types of WAIT:

 

Wait until "Variable conditions are met" allows you to set conditional statements that are checked upon every variable update. A common use case for this is to wait until an ESIGN document has been signed, before progressing to the next step in the workflow.

Conditional statements here can be defined in the same way as routing conditions.

Wait until "Set amount of time", lets you introduce time-based pauses or waits into workflows. For example, authors can introduce a 2 minute forced review of a FORM block before proceeding.

 

Wait until "Date and Time" lets you stop the progress of a workflow until a specified date and time. For example, if you want to set a deadline on submissions, this can be used to auto-progress assessments to completion and prevent end users from re-submitting after a certain date. 

Can end users go back to FORM blocks with WAIT enabled?

• End users are allowed to return to FORM blocks with WAIT enabled, however, the condition on the page will be re-checked when the end user returns. If the condition is already true, then the user will be progressed forward again (effectively preventing them from returning to the FORM block). However, if you are using a wait until "Set amount of time", the timer will restart when the user returns to the FORM block.
• If you would like to prevent the end user from returning to a block, you can use the "Disable BACK button" toggle on the subsequent block as per usual.