Form Templates

Overview of Form Templates

Form Templates are the most critical piece of your Work Type config as they drive what data you can stored against your Work Items and/or collect from external users. Form Templates are all configured in the same place but then can either be used as “Custom Fields” on a Work Item, “Published” for external users to complete or used in a few other specific ways.

Here are the key use cases of Forms:

Published - Public Form / Internal Form

You can publish/share your form to a public URL which allows any user with the link to complete the form. This is great for things like “Contact Us” forms you wish to place on your website as the URL will be the same and every visitor to the form sees a new empty instance of the form.

If your use cases if for internal users only you can also force a logon to the system - great for internal company forms where you still want control over permissions and audit history.

By default forms submitted like this will simply appear in your Team Inbox, however using Automation rules you can decide on other actions like Creating/Updating Work Items and more!

Published - Private Form

Another way to publish/share your form is as a Private Form. Private Forms are specific to a Work Item and a link must be generated using the “Create Form” option in Docs & Comms or links can be generated using Template Syntax (see $formlink within: AgileCase Template Syntax ) to output them onto Document or Email templates.

Private Forms can output other information from their parent Work Item, trigger automations which advance the workflow state of the Work Item and much more. They can also include optional extra security like Dynamic Password protection should you wish users to confirm some key data from the Work Item (like postcode, email address, account number, etc.) before they can access the form.

Work Type - Work Type Custom Fields

In this usage model you configure your Form to be available as Work Type Custom Fields associated with your Work Type. This simply mean your form is shown on any of the Tabs/Blocks of your Work Items and is used to store and collect information on the work.

Work Type Custom Fields may be either “single row” (only a single instance of the form exists for the Work Type), or “multi-row” (multiple instances of the form are created and shown to the user in a “table” format). You can choose or change this when you edit the Work Type Custom Fields.

Work Type - ‘Create New’ Item

This is a special usage where your Form definition is used to layout the form used to create a new item of a Work Type. This allows you precise control over the form used to create a new work item and also to use specific validation rules or link to 3rd party integrations as part of creating a Work Item. You can read more about this usage of Forms here: https://agilecase.atlassian.net/wiki/spaces/ACV2/pages/2580054028/Work+Types#New-Form-Designer .

Creating, Editing and Managing Form Templates & Work Type Custom Fields

Since Form Templates can be shared across work types, or even completely separate to a Work Type they are configured separately in these two settings screens:

Form Templates content and layout and edited first in Custom Forms. If you wish to Publish your form as a link you can also configure all that here as part of the Form Configuration.

If you wish to use your Form as part of the data structure of a Work Type then you must configure that separately under Custom Fields menu option. Once you have configured a Form to be used as a Custom Fields Group for one or more Work Types you will be able to use it within the Page Layout of the Work Type. See https://agilecase.atlassian.net/wiki/spaces/ACV2/pages/2580054028/Work+Types#Custom-Forms-%26-Custom-Fields for more info on how to then display your form on your Work Type.

Creating A Form Template

View Form Templates

Creating a form template is really easy. First visit the “Custom Forms” option from settings (1️⃣) and you will see a list of all your existing Form Templates (2️⃣ ) and the button to Add a new Form Template (3️⃣).

Add New Form Template - Basics

First step when adding a Form Template is to complete the basics like the Name, Description, Keywords and Work Types for the Template:

Name is the name your form is known by on other screens.

Description are used for information purposes so your users can read a explanation of what the form is for and any other help and be added here.

Keywords are used form Searching and Reporting purposes as they allow you to group your forms by purpose/theme etc.

Enabled determines if the form is currently used within all areas of the systems. Setting any form to disabled will immediately remove it from anywhere it is published or any Work Types it is used within.

Work Types decides which Work Types the form is enabled form - if you remove a Work Type from the Form config then similar to enabled the form will immediately be removed from anywhere it is used for that specific work type.

Add New Form Template - Form Designer

The Form Designer allows you to design the layout of your form by dragging and dropping different types of fields onto your form.

Simply click and drag the type of field (1️⃣) you wish onto the form… once the field is on your form (2️⃣) you can click the Green Cog (3️⃣) to configure more details of the field:

Add New Form Template - Form Designer - Field Types

There are numerous different field types you can choose from - including Sections and Tabs which allow you to group parts of your form into specific layouts or split them over a few tabs. Here is a brief explanation of the different types:

Basic

Text Field - the most basic field which just collects text on a single line.

Text Area - a multi-line variant of text field.

Date / Time - specifically for accepting Dates and Times with specific UI and control over date time format and validation.

Options - for collecting values from a fixed list of options. Can be further configured to display as a Dropdown, Checkbox List or Radio Buttons layout.

Numeric - specifically designed for users to enter numbers providing specific validation options. Can be further configured to accept currency numbers with specific support for currency symbols and validation options.

Layout

Tabs - Allows you to add a ‘tab strip’ to your form so longer forms can be split over multiple tabs. When you have a Tab strip on your form Conditional Logic (see: https://agilecase.atlassian.net/wiki/spaces/ACV2/pages/2580217866/Form+Templates#Conditional-Logic-in-Form-Templates ) allows you to show/hide tabs based on other values on your form.

Sections - Allows you to group multiple fields on a Form with a heading and other formatting such as indenting and help text. Sections are also useful for Grouping a large number of fields which you need to then hide/show using Conditional Logic.

Button - Allows you to add buttons to your form. An extra button can allow you users to submit the form at convenient places in the flow of the form to save their progress. It can also be used to change to text shown to the user making it clearer the actions taken after a form is submitted. Currently “Submit Form” is the only action supported by the button but we will be adding more options in future such as “Clear”, “Validate” and more.

File Upload - Allows you to upload files to be linked and versions directly within your forms.

Advanced

Template Button - This button allows users to create a Document or Email from a specific template directly from within your Form. It is great when your Workflow required users to create or review documents after completing data within a form - it means they do not need to leave the screen to do so. The Template Button will save the current Forms progress before rendering the template and allowing users to immediately review it before sending (in the case of an Email).

Work Item Chooser (a.k.a Container Chooser) - allows you to search by Name and Link other Work Items (Cases, Contacts, etc.) to your form. For example you could have a field like “Nominated Person” and then your Work Item Chooser can be set to filter so it only allows user.

User Chooser - allows you to search by Name and Link a User to the Work Item. Involvement mode allows this to update the Involvements of the Work Item - so for example you can set the ‘Case Handler’/'Owner'/'Complaints Handler' Involvements from within a Form.

Signature Button - Signature Button allows the currently logged in to “Click to Sign” which logs their Username, Login IP, Browser Signature and other session info to create an electronic trail of who completed the form.

Integration Button - Integration Buttons allow you to integrate with external services such as Stripe, Zapier, Legl Payments, Yoti Identity Verification and many more coming soon. Typically an integration button will allow you to map specific fields from your Work Item (or current Form) to the inputs of the external service and then return the response of that service which may cause other fields to be updated. It may also redirect the user to the external provider.

For example, a typical use case with Stripe would be to redirect your user to make a payment using Stripe Checkout and then ‘save’ the confirmed payment status back to your Work Item.

Note: You must previously configured your Integration within the Integrations settings before you will see the option for that Integration Button. See Integrations for more details.

HTML Content - HTML content outputs custom HTML, Javascript and CSS. It is useful to display well formatted notes or guidance to your users and also can include AgileCase Template Syntax meaning you can output content from anywhere else in you Work Item and make the content fully dynamic if required.

Add New Form Template - Form Designer - Field Settings

The field settings will vary depending on the type of fields but the Text Field is a good example which covers most of the settings available. A Preview is shown at the top of the Field Setting screen so you can see the effect of your changes in real time.

Display Section

Label - This is the label displayed alongside the field on your forms.

Placeholder - Faded text which can be shown inside an empty field as a “tip” to users on how to complete it.

Description - Help text which is shown underneath your field and can be used to explain to users how the field should be completed.

Tooltip - Text here causes a small ? icon to be shown beside your field and hovering over it will let users see additional help text or tips.

Width/Size/Label Position - These are all related to the layout and formatting of the field label and control.

Prefix/Suffix - These allow you to add a cosmetic prefix or suffix to the field. For example a common usage might be used for Length (m, cm, mm) or weight (kg, g, mg).

Disabled - When enabled the field will not by default allow for any values to be input. Disabled status can be set as default but then Conditional Logic can be used to enable it when a specific condition is met.

Hidden - When enabled the field is not visible on the form. Again this is useful in combination with Conditional Logic if you wish your field not to be shown unless certain criteria are met.

Calculated Field - When enabled the value of the field is determined using a Calculated Value Template (which will then appear within Data section below).

Data Section

Default Value - This is the default value the field will have when the Form is first opened or cleared by a user.

Calculated Value Template (if Calculated Field mode is enabled) - This allows you to set the template used to calculate the value. Templates for Calculated Values follow the same syntax as all other templates within AgileCase (see AgileCase Template Syntax for more on the syntax to use here). This allows you to include both complex logic as well as formulas to set the value of your field.

Refresh On - This determines if the calculate value is refreshed whenever any field on the form is changed or just when the Form is opened (thereby allowing it to be overridden). More refresh options will be added in future.

Validation

Required - field must be completed before the form can be submitted.

Min/Max options - various options for forcing the user to complete the field to min/max length of content.

Custom Error Message - custom message shown to the user when any validation fails.

API

Property Name - This is the ‘internal name’ of the field within AgileCase. The most common usage of this name is within Templates and Reports, ensuring that you can change the label of fields without having to also update any Templates which use it. It also means that the name within template can be shorter and simpler. Once property name is set it becomes ‘locked’ and you need to specifically ‘unlock’ it in order to change it. This locking behaviour ensures you are aware that changing the property name may require you to also update it within any templates where it is used.

Conditional Logic

Conditional Logic is a big topic covered in the follow section.

Conditional Logic in Form Templates

Conditional Logic allows you to specify different Form behaviour based on the data entered in your form or any data associated with your Work Item like. For example you could enable/disable/hide/show fields or sections depending on the values set within your form.

When you are looking at the layout of your form any fields with Conditional Logic will display a Orange Book icon and hovering over that icon will display a tooltip with a text description of the logic.

Conditional are added/removed by clicking the appropriate Add/Delete button and they can be reordered so they take the correct precedence (the last rule to be true will ‘win’).

Each condition is very simple following a IF <trigger field name> <operator> <value> THEN <action> <affected fields list> pattern.

The default behaviour is that if the condition is not met, then the opposite action will be performed. For example if the first condition in the example is not met then the “textField” field would be hidden. In some complex scenarios you may wish that not to happen so you can instead control the behaviour with your own alternative rules - then you can use the “If condition is not met do not inverse action” option to override it.

Publishing a Form Template

Once you are happy with the content, layout and logic of your form template you can optionally publish the template using the Publish tab:

Attaching you Form Template as a Work Type Custom Field Group

Step 1: Create a custom field group based on a Form

A more common use case for Form Templates is to attach them to Work Type configuration as Custom Fields. To attach your Form template to a Work Type you should use the Custom Field settings where you can provide this information.

Here you can give either the same or alternative name to the Custom Field Group and also decide if it should be displayed as a singular form, or as a multi-row table where multiple different instances of the form are created over time and stored in a table.

You can also set the permissions for the Custom Field Group.

Step 2: Edit your Work Type Page Layout to display the Custom Field Group

After you have attached your form as a Custom Field group you need to decide where on your Work Type Pages and Layout it is displayed. This is done using the Work Type Page Layout settings: