Skip to content
Local environment Preproduction — not production data

Multi-step Forms

If you need to gather information from users in a multi-step approach, Factorial Code Forms supports three complementary mechanisms:

  • Steps within a single form — one process, one execution: the form is split into visual steps and the process runs once, after the last step, receiving everything collected.
  • Multi-process flows — several processes, declared up front: the first form lists every step, including the ones served by other processes, and the SDK moves through them on its own, with one navigation for the whole flow.
  • Chaining processes — several processes, decided at run time: every submitted form starts its process, which names the next form to show.

Use steps within a single form when the split is purely visual and all the logic lives in one process. When an intermediate step genuinely needs to execute something (validate against an external system, store a credential the next form needs), declare a multi-process flow if you know the steps in advance, and chain processes when each process decides where to go next. All of them compose: a flow’s steps can be ui:steps fields, and a chained process’s form can itself declare steps.

Declare the steps in your parameters schema’s ui node with ui:steps, assigning each property to a step:

{
"title": "Simple form sample",
"type": "object",
"properties": {
"oneStringField": { "title": "One string field", "type": "string" },
"oneIntegerField": { "title": "One integer field", "type": "integer" },
"oneBooleanField": { "title": "One boolean field", "type": "boolean" }
},
"required": ["oneStringField"],
"ui": {
"ui:steps": {
"config": {
"layout": "tabs"
},
"steps": [
{
"title": "The first step",
"description": "Provide the first bunch of information",
"fields": ["oneStringField"]
},
{
"title": "The second step",
"description": "Provide another bunch of information",
"fields": ["oneIntegerField", "oneBooleanField"]
}
]
}
}
}

The SDK renders one step at a time with a “Next” button. Only the last step’s button submits the form and starts the process execution, which receives every parameter collected across the steps — exactly as if the form had been a single page.

How it behaves:

  • Per-step validation. “Next” validates only the fields on screen (including that step’s share of required); errors block advancing. Fields on later steps never block an earlier one.
  • Free backward navigation. A “Back” button and the step navigation let users revisit any already-seen step without losing what they typed; steps not yet reached stay disabled.
  • No field is lost. Schema properties not assigned to any step are appended to the last step. A ui:steps declaration that cannot be used (fewer than two usable steps, steps not an array) is ignored with a console warning and the form renders as a single page.

The optional config node accepts:

OptionValuesDefaultPurpose
layouttabs | sidebartabsSteps as a horizontal strip, or a vertical list beside the form
nextLabelany stringNextThe intermediate steps’ button label
backLabelany stringBackThe back button label
leaveTitleany stringLeave this step?In a flow across processes, the title of the confirmation asked before going back with unsubmitted values
leaveMessageany stringWhat you entered here hasn't been saved and will be lost.That confirmation’s message
leaveConfirmLabelany stringLeaveThe button that goes back, discarding the values
leaveCancelLabelany stringStayThe button that keeps the user on the step

The last step’s button honors ui:submitButtonOptions as usual (see customization). A step can also set its own nextLabel and backLabel, which win over the config ones for that step: for example { "title": "Credentials", "fields": ["apiKey"], "nextLabel": "Verify key" }. On the last step, its nextLabel replaces the submit button’s text. In a flow across processes, a process step’s labels apply where they make sense even when its form has sub-steps: its nextLabel on the sub-step that submits that form, its backLabel on the one whose Back leaves it. Step titles, descriptions and the labels above are schema content: localize them with fcode.i18n(...) and interpolate variables with mustache syntax, like any other schema text.

Chaining is how forms with no multi-process flow move from one process to the next. During the execution of the first process, simply return a JSON with the next step process slug:

return {
nextProcessId: "collect-shipping-address",
};

The nextProcessId field accepts a process slug (or a process ID). Use the slug so the same process works in every workspace.

By doing this, after a successfull form submission, our SDK will render the form related to the received next process identifier.

In the second, third,… and successive form steps, process executions will receive the previous generated data, and execution results. This allows, for example, collecting information in several steps and using all of them in the last step.

The information from previous steps is published into Factorial Code. If you write this code in the third step:

const {
context: { parameters },
} = fcode;
console.log(parameters);

You’ll see an output like this:

{
"attribute1FromThirdStep": "your-value",
"attribute2FromThirdStep": "your-value",
"steps": [
{
"processId": "collect-customer-details",
"data": {
"attributeFromFirstStep": "your-value"
},
"result": {
"executionResultAttributeFirstStep": "your-value"
}
},
{
"processId": "collect-shipping-address",
"data": {
"attributeFromSecondStep": "your-value"
},
"result": {
"executionResultAttributeSecondStep": "your-value"
}
}
]
}

A multi-process flow declares, in the first form, every step the user goes through, including the steps another process serves. The user sees one navigation for the whole flow, and the SDK moves from one process to the next without any process returning nextProcessId.

Add the flow to the entry form’s ui:steps. Next to the fields steps you already know, a step can name a process with process:

{
"title": "Connect to Linear",
"type": "object",
"properties": {
"linear_api_key": {
"title": "Linear API Key",
"type": "string",
"isSensitive": true,
"ui": { "ui:widget": "password" }
}
},
"required": ["linear_api_key"],
"ui": {
"ui:steps": {
"steps": [
{
"title": "Connect",
"description": "Enter your Linear API key",
"fields": ["linear_api_key"]
},
{
"title": "Map teams",
"description": "Map each Linear team to a Factorial team",
"process": "linear-setup-mapping"
}
]
}
}
}

This is the setup of the Linear integration in the custom app sample. “Connect” collects the API key and submits it to linear-setup, which validates the key and stores it. “Map teams” then renders the linear-setup-mapping form, whose team dropdowns are loaded by its pre-render process with the key just stored.

The rules of the declaration:

  • The first form owns the flow. The SDK reads the flow’s steps from the entry form only. A later form’s ui:steps can split that form, as described below, but its process steps and config are ignored.
  • fields steps come first. They split the entry form, as in steps within a single form, and are submitted together to the entry process. A fields step placed after a process step is dropped with a console warning.
  • A process step is a whole form. It takes the process slug and renders that process’s form; its title and description are what the flow’s navigation shows.
  • A process step can have sub-steps. If that process’s own form declares ui:steps with at least two fields steps, they appear one level below the process step in the navigation (numbered 2.1, 2.2, …) once its form loads. They behave like steps within a single form: only the last one submits, starting that process once. Without its own ui:steps, the form renders on a single page.

When the flow is an installed App’s install or settings form, the Factorial One assistant fills in each step as it opens, once the earlier steps are sent; see lifecycle forms Factorial One fills in.

Every successful submission starts its process, as with chaining, and the SDK then moves to the next declared step. The process does not need to return nextProcessId; it returns its result and, if the next forms need them, variables. fcode.context.parameters.steps and variables carry forward with the same shape as in a chain.

Every submit button except the last one uses config.nextLabel (Next by default). The last step’s button honors ui:submitButtonOptions as usual.

A process can still return nextProcessId to change where the flow goes:

  • A later declared step. The flow jumps to that step, and the steps in between show as skipped.
  • A process the flow doesn’t declare. The flow is dropped: its navigation and history go away, and that process’s form renders on its own, honoring its own ui:steps. steps and variables still carry forward, and the console warns about the reset.
// Jump straight to the "Review" step when the address is already known
if (customer.shippingAddress) {
return { nextProcessId: "review-order" };
}

Users can go back to any step that has already run. The step is pre-filled with what was submitted, so they can review or correct it; a process step with sub-steps reopens on its last sub-step, and all of its sub-steps are reachable. Submitting it again re-runs its process and discards the state of every later step: those steps run again from scratch as the user moves forward.

Going back from a process step drops whatever was typed into it and not yet submitted, sub-steps included. If the user changed any value there, the SDK asks for confirmation first; its wording comes from the entry form’s config (leaveTitle, leaveMessage, leaveConfirmLabel, leaveCancelLabel). Values filled in by schema defaults or a pre-render don’t count as changes, and moving between a step’s own sub-steps never asks, since nothing is lost there.

Default values, variables, and i18n configurations set in the first form in a multi-step flow will be applied to the next steps’ forms.

Another interesting feature is to return a variables object in one form step execution and reuse it in the following steps. This can be done by simply returning a variables node in process execution result:

return {
nextProcessId: "collect-shipping-address",
variables: {
aNewVar: "This is a new var for next form steps",
},
};