Skip to main content
Limited Release
Forms are in limited release and are not generally available. Contact your account manager to request access.

Pre-Submission Workflows

A Pre-Submission Workflow runs action steps while a visitor is still filling out the form, before they submit it. Use one to look data up, validate what the visitor typed, or prepare a value the form needs.

A form's normal Actions run after a submission is accepted. Pre-Submission Workflows run before that, so the visitor sees the result and the form can react to it.

What You Can Do With One​

GoalHow it works
Show looked-up data back to the visitorPopulate a calculated field from a workflow property, such as a contact name resolved from an email address.
Load choices from another systemAdd the items from a workflow result to an Enum or Array of Enum field, with separate submitted values and visitor-facing labels.
Validate an entry against your PSAQuery the PSA, then use a submission condition to block submission when the entry does not match.
Show or hide fields based on external dataUse a workflow property as a term in a field's Conditional Visibility rules.
Prepare a value when the form opensRun a workflow on form load to generate a reference number or look up a starting value.
Notify someone while the visitor is still on the pageSend an email from a workflow that runs on form load.

See the Forms tutorials for complete worked examples.

When Workflows Run​

Each workflow runs on one or more triggers. Select at least one.

TriggerWhen it runs
Field changeEvery time the visitor changes one of the fields you watch. Requires at least one watched field.
Form loadOnce, when the visitor opens the form.
Form submitWhen the visitor submits. The workflow must finish successfully before the form accepts the submission.

You can select more than one trigger on the same workflow. A workflow that watches fields and also runs on submit re-checks its result at submission time.

Repeated values do not re-run the workflow

A Field change workflow only runs again when a watched value actually changes. Clicking into a field and back out without editing it does not start a new run.

Create a Pre-Submission Workflow​

  1. Click Apps in the top bar, then click Forms.
  2. Open the form and select the Pre-Submission Workflows tab.
  3. Select Add Workflow.
  4. Enter a Name. The name appears wherever you select this workflow later, so describe what it produces, such as Look up contact.
  5. In Run this workflow on, select one or more triggers.
  6. If you selected Field change, select the fields to watch in Recalculate when these fields change.
  7. Select Add Action and configure the action steps that produce the values you need.
  8. Select Save Workflow, then save the form.

Each saved workflow appears as a row on the tab with a Watches line listing its fields. Use the row actions to Edit, Clone, reorder, or Delete a workflow.

Fields you can watch​

The Recalculate when these fields change list only offers fields a workflow can safely depend on. A field does not appear if it is hidden, a calculated String field, or a File, Files, or Signature field. You can watch an Enum or Array of Enum whose choices come from another workflow.

The values of the watched fields are available to the workflow's action steps as {{input.fieldName}}. A workflow only receives the fields it watches, so a workflow that watches nothing, such as one that runs only on Form load, has no field values to read.

If a watched Enum has Submit the selected value and label as an object enabled, select {{input.fieldName.value}} or {{input.fieldName.label}} in the action's variable picker. An Array of Enum supplies a list of those objects. See value and label inputs.

A workflow that watches more than one field waits until all of them have a value before it runs. Use that to require a complete set of inputs, such as a ticket number and an access key together.

A watched field that already has a value when the page opens, from a default or from query-string population, starts its workflow right away. The visitor sees the result without typing anything.

Actions store results in custom​

Every action step in a Pre-Submission Workflow stores its results in the custom namespace. The namespace selector is fixed to custom. for this reason.

As you add actions, the tab shows an Available custom properties line listing the properties the workflow produces, such as custom.contact.FirstName. Those properties are what you select later when you map a calculated field or write a condition.

Forms support the same action library as macros, so a workflow can query a PSA, call an HTTP endpoint, run string functions, or send an email.

Produce a plain text value when you need one

Calculated fields accept text values only. When a property is an object or a list, add a Render Text and Store as Variable step to build the exact string you want, then map that property to the field.

Using Workflow Results​

A workflow's properties become available in three places once you save the workflow:

  • Calculated fields: open a String field in the Input tab, select Populate this field with a Pre-Submission Workflow output, then choose the workflow and property. See Calculated Fields.
  • Dynamic choices: open an Enum or Array of Enum field, select Populate this field with a Pre-Submission Workflow output, then choose the workflow, list property, value template, and optional label template. See Calculated Fields.
  • Conditional Visibility: in a field's visibility rules, workflow properties appear in the field list as Workflow: {workflow name} / {property}.
  • Submission conditions: in the Advanced tab, the same terms are available to the submission condition. See Submission Conditions.

After the form is submitted, the values that reached calculated fields are available to the form's Actions as {{input.fieldName}}, the same as any other field. Workflow properties that were not mapped to a field are not carried into the submission.

What the Visitor Sees​

While a workflow runs, each field it populates shows a spinner and the text "Calculating…". When the run finishes, the field shows the value and the text "Calculated successfully."

The submit button reflects the state of the page. It reads Calculating... and stays disabled while any workflow is still running, then returns to Submit.

If a workflow fails, the affected field shows a red message, and the form shows a message above the submit button. The form does not accept a submission that depends on a workflow that did not finish successfully.

Calculation sessions​

When a visitor opens a form that has Pre-Submission Workflows, the form opens a calculation session that lasts 30 minutes. If the visitor leaves the page open past that point, calculated values clear and the form reconnects automatically. The visitor sees "This calculation expired. Please try again." on affected fields.

On forms that use the Cloudflare Turnstile security check, the visitor completes the check again to restart calculations.

Limits​

LimitValue
Calculation session lifetime30 minutes
Calculations running at the same time for one visitor10
Length of a value written into a calculated field10,000 characters
Dynamic choices used for one field1,000
Total size of calculated text, dynamic choice values and labels, visibility data, and the complete calculation response sent to the visitor100,000 bytes

Public form requests are also rate-limited per IP address. See Forms for the general submission limits.

Large lookup results do not count toward this limit unless the form sends them to the visitor as calculated text, choices, or visibility data.

Reviewing Workflow Runs​

A form attempt keeps its Pre-Submission Workflow runs and accepted submission together in one history. Open the saved form and click View History to find its runs in Form History. Open an attempt, then expand a workflow's entry in Execution Logs to see its inputs, action steps, and results.

For example, a visitor might enter an incorrect ticket number, correct it, and submit:

RunWhat the history shows
Look up ticket, first runThe lookup failed.
Look up ticket, second runThe lookup succeeded with the corrected number.
SubmissionThe form accepted the visitor's values and started its normal Actions.

The history keeps both lookup runs. Reusing an existing calculation result does not add another run.

Use the Submission filter's Submitted, Not submitted, or All options to choose which attempts to review. A completed lookup does not mean the visitor submitted the form. Not submitted includes attempts where the visitor left, a check blocked submission, or the attempt expired.

Submission and processing have separate outcomes: a submitted form can still have a failed action. Open its execution logs to find the failing step.

Replay runs the accepted submission's original input through the form's current Actions. It adds another execution to the same history and does not repeat the Pre-Submission Workflows. Attempts without an accepted submission cannot replay; open the public form to start a new attempt instead.

Security​

  • Action steps stay on the server. The browser never receives a workflow's configuration or its action list.
  • Only the properties a form actually needs reach the browser: values mapped to calculated fields, rendered dynamic choices, and properties referenced by a visibility condition. The workflow configuration and raw choice source data stay server-side.
  • At submission, the server recalculates which values belong in calculated fields from its own stored results. Values edited in the browser for those fields are discarded.
  • Values for hidden fields come from the form's configuration and query string, not from the browser, so a crafted request cannot change what a workflow receives.

Troubleshooting​

What you seeWhat it means
"This value could not be calculated."The workflow ran but the action steps failed. Open the form attempt's history and inspect the Pre-Submission Workflow run to see which step failed.
"The workflow did not return text at the selected property."The workflow finished, but the mapped property was empty or was not a text value. Check the property path, or add a step that renders the value as text.
A dynamic choice list is emptyThe selected property did not contain a list, or none of its items produced a nonblank value. Check the list property and Value Property template.
"This calculation expired. Please try again."The visitor's 30 minute session ended. The form reconnects and recalculates.
"The field configuration changed."Someone edited the form while the visitor had it open. The visitor reloads the form to pick up the new configuration.
"The form configuration changed. Recalculate the form and try again."The form was saved between the visitor's last calculation and their submission. The visitor resubmits after the form recalculates.
"A pre-submission workflow did not finish successfully."A workflow the submission depends on has no successful result. The form blocks the submission until it does.
"Too many calculations are pending."The visitor has 10 calculations running at once. Wait for them to finish.
"This calculation produced too much data to display in the browser."One calculation exceeded the 100,000-byte limit. Use fewer dropdown choices, shorter choice labels, or shorter calculated output.
"These calculations produced too much data to display in the browser."The complete response exceeded the 100,000-byte limit. Use fewer dropdown choices, shorter choice labels, or shorter calculated output.
The Property list is emptyThe workflow has no actions yet, or its actions produce no custom properties. Add an action step and set its results variable.
Delete is unavailable on a workflowA calculated field or a condition still references it. Remove those references first.
Editing a form that is in use

Changing a workflow, its watched fields, or a field mapping invalidates calculations that visitors already have open. Those visitors reload the form before they can submit. Make changes to busy forms during quiet periods.