Geocortex Workflow Help
Open topic with navigation
Forms allow end users to enter information for the workflow to operate on. For example, a workflow that locates an address for the user would include a form where the user enters the address.
In addition to gathering textual information like addresses, you can use forms to get dates, numbers, map locations (geometries), and more from the user, or to get the user to select from arbitrary items that are defined in the workflow or retrieved from a database when the workflow runs.
Form elements are the building blocks of forms. When you design a form, the Toolbox contains form elements instead of activities. To build the form, you drag form elements from the Toolbox to the design surface and place them in the order that you want them to appear to the end user. You then configure each element's properties to customize the behavior and appearance of the element.
The type of a property defines what types of values the property can have. For example, the Visible property's type is Boolean, which means its value can be
false. Perhaps the most common type is string, which means that the property's value is text. Some properties have more than one type. For example, the
value property can be any type.
In a workflow, you can use the Get Form Element Property activity to find out the current value of a particular property. You can change the value of a particular property using the Set Form Element Property activity.
Geocortex Workflow has the following customizable form elements:
Auto Complete: A text input that presents suggestions based on what the user types.
Button Bar: A list of buttons.
Check Box: A single checkbox input.
Check Group: A list of checkbox inputs.
Custom: Custom developed form elements.
Date Picker: An input that allows the user to select a date using a calendar.
Date Time Picker: An input that allows the user to select a date and time using a calendar and time selector.
Drop Down List: An input that allows the user to select a single item from a list.
File Picker: An input that allows the user to select one or more files from the file system.
Geometry Picker: An input that allows the user to draw one or more geometries on a map.
Header: The form's header, which contains the form's title.
Horizontal Rule: A horizontal line used to separate content.
Image: An element that displays an image.
Item Picker: An element that displays a list of items and optionally allows the user to select items.
List Box: An input that allows the user to select one or more items from a list.
Number: An input that allows the user to select a number.
Number Slider: An input that allows the user to select a number using a slider control.
Password Box: A single-line text input that conceals the text so that it cannot be read.
Radio Group: An input that allows the user to select one option from a set of options.
Scanner: An element that allows the user to scan a barcode or QR code using their device's camera.
Section: An element that groups the elements in a form into sections.
Text: An element that displays text.
Text Area: A multi-line text input.
Text Box: A single-line text input.
Time Picker: An input that allows the user to select a time.
In Geocortex Workflow, an event is something that happens in a form. This could be an action by the user, like a button click, or a step in the form's life cycle, like the validation step after the user has submitted the form.
Events allow you to monitor what is happening in the form and customize how the workflow responds. For example, you could monitor a checkbox and show additional form elements if the user selects the checkbox. To customize the response, you add a subworkflow that defines the custom behavior. When the event occurs ("fires"), the subworkflow runs.
Adding an event subworkflow overrides Geocortex Workflow's default behavior for handling events. Having an event subworkflow is your way of telling the workflow that you want to take control of how the event is handled.
Sometimes, you may want to have both custom behavior and the default behavior. In this case, you can add a Propagate Form Event activity to the event subworkflow. The Propagate Form Event activity instructs the workflow to perform the default behavior after the event subworkflow completes.
Different types of form elements support different types of events. For example, radio groups have
change events, whereas button bars have
submit events. Each element in a form has its own events. For example, if a form has two radio groups, each radio group has its own
Geocortex Workflow has the following types of events:
load: When a Display Form activity runs, the form elements load. Every form element has a
load event that tells you when that element has finished loading.
change: When the user makes a selection or enters some input, the
change event fires. The
change event can fire zero or more times, depending on whether the user enters anything for that element.
click: When the user clicks a button, the
click event fires.
cancel: When the user cancels the action, the
cancel event fires.
validate: When the user clicks a button that causes validation, the
validate event fires.
submit: When the user clicks a button that submits the form and all form elements have passed validation, the
submit event fires.
For more information about a particular event, refer to the documentation for the form element.
Some events can fire multiple times for the same form element, causing the event subworkflow to run multiple times. For this reason, we recommend that you make sure that event subworkflows are not computationally intensive or long running.
To add a form to a workflow, you use the Display Form activity. Like other activities, the Display Form activity has properties and inputs that you configure for it. In addition, the Display Form activity has a built-in designer that you use to build forms. To open the designer, double-click the Display Form activity in the flowchart.
When you create a new form, the form has two elements—one for the form's title and one for the Submit and Cancel buttons. These elements are automatically displayed at the top and bottom of the form respectively. When you add elements to the form, add them in between these two elements, in the order that you want them to appear to the user.
To configure a form element, select the element in the preview. The element's settings open at the right.
New form, showing the form elements that you use to build forms, a preview of the form, and the selected element's settings
The main steps to configure a form are:
Drag a Display Form activity to the design surface.
Double-click the Display Form activity to open it for editing.
Build the form by adding and configuring form elements:
Drag a form element from the Toolbox and drop it in the preview area.
The preview shows the elements in the order they will appear when the workflow runs. You can drag the elements within the preview to re-order them.
Click the form element to select it.
The element's settings open.
Configure the element's settings.
For information about the settings for a particular form element, refer to the section about that element.
Select a form element.
In the Events area, click the arrow to show the events.
Click Add beside the event that you want to customize.
A blank subworkflow opens.
Build the subworkflow the same way you build the main workflow—drag activities from the Toolbox to the design surface, configure their settings, and connect them into a flowchart.
When you have completed the subworkflow, click Display Form in the breadcrumbs to return to the form preview.
You can re-open the subworkflow from the element's Actions menu or by clicking Edit in the Properties panel.
When you are satisfied with the form, click Start in the breadcrumbs to return to the main workflow.
You can improve the appearance and effectiveness of your forms by formatting the text that you display to the user and including hyperlinks in the text. Geocortex Workflow Designer supports Markdown, a simple method of adding formatting like headers, lists, bold text, hyperlinks, and more.
To use Markdown, when you configure the text that you want to format, you precede or surround the text with the Markdown characters for the formatting you want. For example, if you surround a sentence with asterisks (*), (*This sentence is bold*), then the sentence will appear bold in the form (This sentence is bold).
The form preview shows the formatted text, so you can see what the formatting will look like in the running workflow.
If you want to use a Markdown character as itself in a setting that supports Markdown, put a backslash (\) before the character. For example, if you want a hash at the beginning of a line (#10 Downing Street), enter \# at the beginning of the line (\#10 Downing Street). This prevents the hash from being interpreted as the Markdown character for a heading.
Some formats require more than one line. For example, a list with three items requires three lines. However, some settings in Workflow Designer do not allow you to enter more than one line. For example, you cannot enter multiple lines into a Title property. If pressing Enter does not go to a new line when you are configuring a setting, then the setting only allows one line.
If the information that you want to display requires more than one line, add a Text element to your form. The Text element's Description property allows you to enter as many lines as you want.
To check whether a particular setting supports formatting, hover the pointer over the setting's help icon in the Properties panel. The help indicates whether the setting supports formatting. For quick access to the Formatting to Use in Forms table, click the More... hyperlink.
Formatting to Use in Forms
This is *italics.*
This is _italics._
This is italics.
To display italics text, put an asterisk (*) or an underscore (_) at each end of the text.
This is **bold.**
This is __bold.__
This is bold.
To display bold text, put two asterisks (**) or two underscores (__) at each end of the text.
# Main Heading
## Second-level Heading
### Third-level Heading
To display a top-level heading, put a hash (#) at the beginning of the paragraph. Put two hashes (##) for second-level headings, three hashes (###) for third-level headings, and so on.
The site at `https://www.geocortex.com` provides samples.
The site at
To display a single line or part of a line of text in a monospace font and preserve the number of spaces in the original text, put backticks (`) at the beginning and end of the text.
You cannot put Markdown within Inline Monospace text. Characters like asterisks (*), underscores (_), and hashes (#) appear exactly as you enter them in the configuration—they are not interpreted as Markdown characters in Inline Monospace text.
The pattern to put a hyperlink in the text is:
Alternatively, if you want to use the URL as the link text, you can use this pattern:
This is a horizontal line.
This is a horizontal line.
To enter a horizontal line, type three or more underscores (___) on a new line.
This is the first line.\
This is the first line.
To go to a new line, type a backslash (\) and press Enter.
The New Line Markdown has no effect in settings that only allow a single line.
- First list item
* First list item
To display a bulleted list, put a dash (-) or an asterisk (*) at the beginning of each list item.
The Bulleted List Markdown will not render a multi-line list in a setting that only allows a single line.
1. This is the first step.
1) This is the first step.
1. This is the first step.
To display a numbered list, put a number followed by a period or a closing bracket at the beginning of each step, for example, 1. or 1).
The list starts at whatever number you use in the first step. It doesn't matter what numbers you use in subsequent steps—the numbers will increment by 1.
To end the list, press Enter twice at the end of the last step.
The Numbered List Markdown will not render a multi-line list in a setting that only allows a single line.
Forms are typically used to gather input from the user. In a typical scenario, the user fills in the form and then submits it. If the input has errors or omissions, the user makes corrections and resubmits the form. This cycle of making corrections and submitting the form is repeated as many times as necessary. When the form is free of errors, the input is ready to be processed. The form closes and the workflow continues running at the next activity after the Display Form activity.
Buttons are used to control form validation and submission. When you configure a button, you specify whether the button causes validation and/or submits (exits) the form. When the user clicks the button:
If the button causes validation, the validation cycle is repeated until the form is error-free.
If the button submits the form, the form closes and the workflow continues running at the next activity after Display Form.
By default, forms have a footer button bar with Submit and Cancel buttons. The Submit button causes validation and submits the form. The Cancel button submits the form without validating the user's input.
Every new form you create has a footer button bar. You can modify the footer button bar's properties (except the Element ID), but you cannot move or delete the button bar. If you do not want your form to have a footer, clear the button bar's Visible checkbox to hide the button bar.
When the user clicks a button that is configured to cause validation, validation is performed for each element in the form that has validation configured. There are two ways to configure validation for a form element:
validate event to the form element.
Select the form element's Required checkbox.
In the following screen capture, the user has submitted the form without selecting a state. Because the state is configured to be required, the form will not close until the user enters the state.
Example of a validation message in a form
This example illustrates one way to validate an email address in a
validate subworkflow. The subworkflow looks like this:
Flowchart for a subworkflow that validates an email address
validate subworkflow uses a regular expression to compare the user's input to the pattern for a valid email address (), and then branches based on whether the input matches the pattern or not (). If it doesn't match (), the subworkflow sets an error on the input element and the error message displays in red text above the element. If the input does match the pattern (), the subworkflow clears any error that was previously set on the input element.
Error message on the Email Address text box
To configure a validate subworkflow that tests the validity of an email address:
Add a text box with a
Edit a Display Form activity.
Add a text box to the form and change its title to Email Address.
Select the text box to show the Properties panel, and then click the arrow beside Events to show the events.
Click Add beside the
A blank Event subworkflow opens.
Test whether the input is valid:
Drag a Regular Expression Matches activity to the design surface and connect it to the Event block.
In the Text input, type an equals sign (=) followed by a reference to the user's input, for example,
In the Pattern input, type or paste the regular expression that defines the pattern for the email address, for example:
Branch based on whether the input is valid:
Drag an If activity to the design surface and connect it to the Regular Expression Matches activity.
Set the Condition input to the result of the Regular Expression Matches activity, for example,
Drag a Set Form Element Error activity to the design surface and connect it to the If activity's False branch.
Set the Element ID input to the Element ID of the text box.
Set the Error input to the error message that you want to display above the text box, for example,
Email address is invalid.
Drag a Clear Form Element Error activity to the design surface and connect it to the If activity's True branch.
Whenever you use a Set Form Element Error activity, make sure you also use a Clear Form Element Error activity to clear the error. Otherwise the form may get stuck in an invalid state.
Set the Element ID input to the Element ID of the text box.
Click Display Form in the breadcrumbs to return to the form preview.
You can re-open the subworkflow from the text box's Actions menu or by clicking Edit in the Properties panel.
After the user has entered information into a form and submitted the form, you can use the user's inputs in other activities. To access a form's inputs, you use the form's
state output in an expression. The
state output gives you access to the individual inputs that the user entered in the form. An expression to access a form element looks like this:
The parts of the expression are:
formID: The ID of the form from which you want to access a user input.
state: A form's
state output gives you access to the individual inputs that the user entered in the form.
elementID: The ID of the individual form element that you want to access.
value: The value that the user entered into the element.
Example - Enter an Expression to Access Another Activity’s Output
To close a form and return to the main workflow in Workflow Designer, click Start in the breadcrumbs or press Ctrl + Alt + Home.
Use the breadcrumbs to return to the main workflow