Multi-step Forms

If you need to gather information from users in a multi-step approach, Factorial Code Forms supports two 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.
Chaining processes — several processes, one execution each: 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. Chain processes when an intermediate step genuinely needs to execute something (validate against an external system, precompute variables for the next form). Both compose: a chained process’s form can itself declare steps.

Steps Within a Single Form

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.

Configuration

The optional config node accepts:

Option	Values	Default	Purpose
`layout`	`tabs` \| `sidebar`	`tabs`	Steps as a horizontal strip, or a vertical list beside the form
`nextLabel`	any string	`Next`	The intermediate steps’ button label
`backLabel`	any string	`Back`	The back button label

The last step’s button honors ui:submitButtonOptions as usual (see customization). 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 Processes

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"
      }
    }
  ]
}

Variables in Multi-step Forms

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",
  },
};