Getting Started with Factorial Code Forms

Forms opened from Factorial

A form that Factorial’s users open from inside Factorial is one entry point of a Factorial Action. Its switch lives in the Trigger from Factorial section of the process dashboard, next to the action’s title, description and the other entry points, and in the factorial.form key of metadata.json. This guide covers the form itself — the schema, the embed and who may open it — and applies to both.

Enable Factorial Code Form

The first step is to create your Factorial Code process and configure the input parameters that will define form fields.

Tip

The input parameters configuration for the form on the Overview page would be:

{
  "title": "Sign-Up Form",
  "type": "object",
  "properties": {
    "name": {
      "title": "Your Name",
      "type": "string"
    },
    "email": {
      "title": "Your Email",
      "type": "string",
      "format": "email"
    },
    "password": {
      "title": "Your Password",
      "type": "string",
      "isSensitive": true,
      "ui": {
        "ui:placeholder": "Use a Secure Password"
      }
    },
    "yourIdDocument": {
      "title": "Upload Your ID Document",
      "type": "string",
      "x-fcode-file": { "accept": [".pdf", ".png", ".jpg"] },
      "ui": {
        "ui:widget": "file"
      }
    },
    "plan": {
      "title": "Which Plan Do You Want to Use",
      "type": "string",
      "ui": {
        "ui:widget": "radio"
      },
      "enum": ["FREE", "STARTER", "GROWTH"],
      "default": "STARTER"
    }
  },
  "required": ["name", "email", "password"],
  "embedFormOptions": {
    "loadingOverlayContent": "Creating a New User..."
  }
}

With these input parameters configured, it is time to enable the forms feature. Simply visit the process Dashboard and enable the Form switch in the Trigger from Factorial section.

Restrict who can open the form

The Authentication field next to the Forms flag decides who may read the form schema and submit it:

• Factorial users of the company that installed the app: the form URL is closed to anonymous requests. The only credential it accepts is a Factorial Code token of a member of the workspace, which the playground link on the process dashboard sends for you; every other request gets a 401.
• Public access: anyone who knows the form URL can open and submit it.

New forms are created requiring a Factorial user. Forms enabled before this field existed keep behaving as public forms until you change them.

Caution

Factorial does not yet sign customers in to protected forms: a form embedded in Factorial is requested without a credential, so a protected form answers it with a 401. Until that ships, set a form that customers open from inside Factorial to Public access.

The same setting lives in the process metadata.json as form.authMode, so it travels with your code through fcode pull and fcode push:

{
  "form": { "enabled": true, "authMode": "FACTORIAL" }
}

Public forms carry no authMode entry. To lift protection from a form that currently requires a Factorial user, set "authMode": "NONE" explicitly — omitting the field leaves the form protected.