Forms

This article covers all the features related to the form-building process, for a simple guide to get started building forms check out the Build My First Form article.

TABLE OF CONTENTS

• Forms List
• Creating A Form
• Builder
  • Create from Template
  • Create from PDF Form
  • Add New Element
    • User Inputs
    • User Selections
    • Date & Time
    • Informational
    • Advanced Elements
    • Integration elements
  • Forms Configuration
• Workflow
• Settings
  • Success Message
  • Submit Button
  • Tags
  • Authentication
  • URL Suffix
• Developer Tools
  • Receipt Generation
  • Developer Keys
• Summary
• Form Lock
• Getting Help

Forms List

The forms list page will show you all of the forms in your environment. The form list includes a search bar and tag filtering allows you to easily find the form you are looking for. 

Each form in the list will show the form name, the description, any tags, the workflow events configured for the form and if the form is public or private. Use the three dots to open the form menu.

The form menu

• Copy - Create a copy of the form
• Delete - Delete the form
• Download - This will download the JSON definition of the form
• View Schema - This option allows you to view the JSON schema of that specific form
• Migrate to Environment - Migrating the form allows you to create a copy of the form in another environment.
  For more information check out this article.

Creating A Form

On the Forms list page, you’ll see a plus button at the bottom right of your screen, clicking this button will show a pop-up where you can enter the name of your form and set the authentication. 

Builder

After creating your form you are automatically navigated to the builder tab where you start building your form.

When starting to build your form you have 3 options: 

1. Create from Template: Use one of the premade templates to get started quickly.
2. Create from PDF Form: Automatically generate form elements based on an uploaded PDF Form.
3. Add New Element: Start building your form manually by adding individual form elements.

Create from Template

When starting to build a form you can open the list of templates using the "Create From Template" button. This will open a pop-up showing a list of available templates to choose from. 

For more information check out this article.

Create from PDF Form

When starting to build a form you can instead upload an existing PDF form using the "Create From PDF Form" button. This will open the file picker allowing you to upload a PDF. This process can take between 10 - 30 seconds to generate all of the form elements. 

Add New Element

Clicking the add new element button will allow you to start manually building out your form. To get started see the list of form element types below:

User Inputs

• Text: Allows a user to enter a single line of free-form text.

• Text (Multi-line): Allows a user to enter multiple lines of free-form text.
• Number: Allow the user to add numbers. This will display the numerical keypad to the user for ease of use.
• Email: The email element customises the keyboard on mobile and tablet devices making it easier to enter an email. 
• Phone Number: The phone number element customises the keyboard on mobile and tablet devices making it easier to enter a phone number.
• Barcode Scanner: This element turns your device's camera into a barcode scanner, you can even restrict the specific types of barcodes you are scanning against.

User Selections

• Radio Button: Allows the user to select one item from a list of options.

• Checkboxes: These will allow the user to tick multiple items from a list of options.

• Select: Show a drop-down select box that will allow the user to choose from a list of options.

• Autocomplete: Similar to the select element but allows the user to limit the list by typing in the input and filtering the list to match what is typed.

• Switch: The switch element can be set to either off or on.

Date & Time

• Date: Allow the user to select a date.

• Date and Time: Allow the user to select both the date and time.
• Time: Allow the user to select a time.

Informational

• Heading: Headings allow you to add headings to your form.

• Information: This can be used to add informative text to a form.
• Image: The Image element can be used to add images to the form.
• Section: Sections allow for collapsable groups of elements helping to streamline form navigation.

Advanced Elements

• Camera: This will allow the user to take a photo using the native camera of their device, or allow you to upload a photo, including the ability to annotate photos.
• Repeatable Set: Create a repeatable set of form elements, you can add as many of these sets as needed when completing the form.

• Signature: This element allows the user to sign the form using the touch screen or mouse of the device.

• Calculation: This element allows you to take the input and values of numbers, check boxes, single select and other calculation elements and create complicated calculations with them.
  For more information check out this article.
• Location: The location element will display a map with the user’s current position. The user can zoom in and out, and move the pin to update their location if needed.
• Files: Files Element can be used to capture any external files into the form.
• Not a Robot: This is a CAPTCHA element that added an extra layer of security for your public-facing forms.
• Form: The form element allows you to place an existing form inside another form.
• Summary: The Summary element can display the inputs of other elements elsewhere in the form.
• Checklist: This element is like a radio button but includes built-in conditional notes (multi-line text) and media (files)

Integration elements

These are form elements that are associated with a specific integration.  

• Google Address: This element allows users to search on Google address services to search on a list of valid addresses. 
  For more information check out this article.
  
• Freshdesk Dependant field: Allow for form users to fill in a Freshdesk dependant field on the form.
  For more information check out this article.
• ESRI ArcGIS Web Map: This allows users to view an ESRI map in the form.
  For more information check out this article.
• Geoscape Address: This element allows users to search on Geoscapes address services to search on a list of valid addresses. 
  For more information check out this article.
• Point Address: This element allows users to search on NSW Point address services to search on a list of valid addresses.
  For more information check out this article.
• Civica Street Name and Name record: These elements allow for the population of Civica street names and name records. 
  For more information check out this article.
• BSB: The BSB element will allow users to enter a 6-digit BSB and validate that it is a real BSB
• ABN/ACN: The ABN/ACN element will take in an ABN or ACN and check that it is valid. 
• Liquor Licence: The element allows users to search on a business name or liquor licence number and return additional details about the licence.
  For more information check out this article.

Element Details

Clicking on an element will open the element details.

• Label - The label is what will appear on the form next to the element. 
• Hint - The can be used to add an information (i) icon to the label of the element or add additional hint text below the label.  
• Placeholder - Placeholders are greyed-out text that appears in the element input usually showing the user an example of what they should be entering. 
• Default Value - Some form elements can be set in the forms builder to display default data.
• Required - Yes or No (Default No), this ensures that this element must be filled out before the form can be submitted.
• Required Message - This input allows you to add your own custom message if the user does not fill in this element
• Read Only - This will make the element unable to be edited. 
• Show Conditionally - This option is used when you want the element to only be shown under a certain condition
  For more information check out this article.

Advanced

• Name - The name is how the element will be referred to in the submission data, but by default all special characters are removed, the case is changed to lowercase and spaces are replaced with underscores. 
• CSS Classes - CSS classes can be added to any element and used in the Advanced Styling section to target elements with the same classes. 
• Autocomplete Attributes - Uses HTML to take advantage of autofill and assistive technologies, such as using 'given-name' to automatically fill in a user's first name. This can be used on all User Input and Date & Times elements as well as Select, Autocomplete and Checklist elements. 
  • Here is a link to common autocomplete element attributes.
• Hide Element - Hide the element so that it is not visible to the form's user.
  • Hidden elements will also not be visible in approvals or in an approval form.
  • Hidden elements will still be included in the submission data and any submission PDFs.
• Data Lookup and Element Lookup - These are used to call APIs to either populate existing form elements with data or create new elements.
  For more information check out this article.
• Meta Data - Add JSON data to the element allowing developers to consume the data.

Forms Configuration

Form Name

This is the name of your form, this can be changed on any of the form tabs.

Add Pages

To help streamline and organise your forms they can be broken up into separate pages. This can be done by clicking the Add Page button. Pages require a title, and at least one element. Pages can also be conditionally shown to create more dynamic forms.

Preview

The Preview button will show you a preview of your form. You are able to interact with the preview to ensure everything is working as expected. When you make a change to the form you must save the changes before they will appear in the preview.

Launch

The launch button allows you to open your form in another window. If you have multiple apps configured for your form you can open the form in any of the associated apps.

Drag and Drop

The builder makes use of the drag-and-drop capability to help create a simple-to-use interface.

• Re-order elements - You are able to click the drag handles (the 2 horizontal lines) on the far left of each element. These allow you to drag the element up or down the page to reorder your form elements. 
• Move elements between pages - You are also able to use these to move the element between pages, by dragging the element and holding over the page title. 
• Re-order Form Pages: Finally, you are able to re-order your form pages by dragging and dropping the page left or right to create your desired order.

Workflow

When a form is submitted, the form data is automatically saved to a cloud data store.

In addition to this, there are a number of other workflow events that can be triggered as part of a submission.

For more information check out this article.

Settings

Settings

Description: A brief description of the form and what it contains.

Associated Apps: Select from a drop-down the apps you want this form to appear in.

Navigation

These controls allow you to set where you want your user to go when clicking the cancel or submit button.

• My App: Take the user back to the app home screen after the form has been submitted.
• Back: The users is taken back to the previous page they were on
• Close Page: The page is closed
• Redirect URL: The redirect URL will take the user to the specified URL. This can be used to take users to a company website, receipt page, thank you screen etc.

Success Message

Display a button to download the submission PDF

This switch will allow you to add a Download PDF button to the submission message, allowing users to immediately download a copy of the PDF after completing the form. The PDF customisations are the same as any workflow event, allowing you to exclude specific elements, rename the PDF, and add the submission Id or page breaks. 

Customise the success message

This switch allows you to customise the content of the submission message. Allowing you to include additional context or links to other import URLs. To modify the existing message click the Use Default button to start modifying the default message. 

Submit Button

Conditionally enabling the submit button will ensure that the submit button is disabled until the specific conditions are met. For example, if you want to ensure that a user has completed a declaration or agreed to all of the terms and conditions before the submit button becomes enabled. 

Tags

Tags allow for an easy way to filter and sort your forms in the forms list.

Authentication

This setting determines the form's accessibility, designating it as either Public or Private.

Public - The form is accessible to any user without requiring authentication to an app.

Private - Access to the form is restricted to authenticated users with an account on the associated app.

Access Period

This setting allows you to configure a Start and End date and time for your forms. If the form is accessed outside of this date range the users will see an unpublished message instead of the form. The Start and End dates are both optional, if neither is configured the form is always available. If only a Start date is configured the form will only be available after that Start date. If only an End date is configured then the form will only be unavailable until that date.

Unavailable Message 

When adding a start or end date to your form, you are able to configure the message that will appear whenever anyone tries to access the form URL outside of your published dates. From here you can use the rich text editor to include any important information. 

Submission Title

The submission title can be used to add a more descriptive title to your submission it can include meta data from the form (e.g Form Name), and can also include content from the form (e.g Name and Email). To add content from the form use the following naming convention {ELEMENT:<element-name>}, see the example below.

The submission title will be used as the title for any approvals created as part of the form submission. This can also be searched on in the Approvals app making it easy for you to find the approvals you are looking for. 

The submission title will also replace the default draft name, when a user saves a draft of the form. 

Finally the submission title is also visible in the Submissions menu, you are able to view and search submissions on the submission title allowing you to quickly find the submission you are looking for.

URL Suffix

The Form URL Suffix allows you to replace the form ID (e.g. 1234) with human-readable text (e.g. application-form)

Note: Be aware that if you add a suffix to a form and then change it the original suffix will no longer work.

Developer Tools

Personalisation & Receipt Generation

Personalisation & Receipt generation allow you to configure an API endpoint that triggers on form load. 

For more information check out this article.

Validation

Validation allows you to configure an API endpoint to run server-side validation on form submission. 

For more information check out this article.

Receipt Generation

The Receipt Generation feature enables the creation of custom Receipt IDs as part of the form submission process. By configuring an API endpoint, you can fully customize the receipt identifier, which is automatically generated upon form submission.

For more information check out this article.

Developer Keys

This feature assigns Developer Keys to your form, giving them the permissions to access the form's data. Only Submission Data Keys can be configured on a form.

For more information check out this article.

Autosave

Whenever a form is in use the form with automatically save to ensure that the user's progress is not lost. If the user opens the form and there is autosave data detected then the form will show a pop-up asking the user if they would like to start again or continue with the autosave. We have added the ability to skip the pop-up ensuring that the user always continues with their autosave data. 

To enable this turn on the "Automatically resume form if autosave data is present"

CSS Classes

This section allows you to add root level CSS properties directly to your form. The CSS properties that are applied here will apply to the form in the forms list menu item, and directly to the form itself.

Summary

Information

From here you can see the information about the form, 

• Form ID: The specific identifier for the form
• Created: The date and time the form was created 
• Form link(s): The links to the apps that contain this form. You are also able to share your form by clicking the share button, for more on this check out this article.

Versioning

Versioning allows team members to view the date and times of when a form has been saved, the name of the team member who had saved the form and the version name. In addition to this team members are able to rolled back to a previous version restoring the previous versions form configuration.

Note that only 10 non-named versions of the form can be saved at any one time, if an additional save is made the oldest version is removed.

Versions can have names added, when a name is added the version will persist regardless of how many times the form is saved. Versions can also be deleted, when a version is deleted it will be removed from the list of versions. If the version being deleted is within the 10 most recently saved versions then it will revert to being an un-named version.

When migrating a form you can also select which version of the form you would like to migrate to the new environment.

Form Lock

When a form is being edited the Save button will become enabled. This will allow you to save any of the changes you have made. While the Save button is enabled the form will be locked for any other team members, this means that no one else will be able to edit the form while you are editing it. This prevents the possibility of your work being overwritten. A form can be unlocked by another user if the need is required. 

Getting Help

If you need any assistance with Forms please reach out through the Report Issue menu or email support@oneblink.io.