fcode-forms
Embed a Factorial Code process's input-parameter form on a webpage — embed methods, version pinning to the stable alias, what a public form means for the process behind it, driving behavior from the process return value, styling and themes, multi-step flows, and file uploads. Use when embedding, configuring, styling, or wiring up a Factorial Code (fcode) form.
How do I install this agent skill?
npx skills add https://github.com/factorialco/factorial-code-skills --skill fcode-formsIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill provides instructions for embedding and configuring Factorial Code forms. It includes robust security guidance regarding secret management and input sanitization. A potential attack surface for indirect prompt injection exists through the AI assistant integration, although the skill provides specific mitigation advice and all external resources belong to the verified vendor.
- Socketpass
No alerts
- Snykwarn
Risk: MEDIUM · 2 issues
What does this agent skill do?
Factorial Code — Forms
A Factorial Code Form embeds a process's input-parameter form on any webpage.
Each submission starts a process execution with the form data, and the result is
handled in-page (messages, redirects, callbacks). For the schema itself, see
fcode-json-schema.
Gotchas
- The form is the process's
parametersSchema.json— there is no separate form definition. To change fields/validation/labels, edit the schema, not the embed code. teamandprocess/processIdare both mandatory on every embed, and both take slugs — not the per-workspace UUIDs.- Always pin the embed to the
stablealias (data-fcode-form-process-version="stable"/processVersion: "stable"). An unpinned form runs the current version, so everyfcode pushchanges it immediately. Details below. - An unknown version or alias doesn't fail the form — it silently runs the current version (see "Pin the form to a version").
- An employee field (
"ui:widget": "employee") has no picker in an embedded form — it renders a plain select when the field lists its choices, and a notice otherwise. The picker only exists in forms opened from Factorial; seefcode-json-schema. - The
Formsflag must be enabled — in the Trigger from Factorial section of the process Dashboard, or viafactorial.form.enabled(legacy:"form": { "enabled": true }) in the process'smetadata.json+fcode push— or the embed won't render. - A form requires a Factorial identity unless you release it. By default a
form is reached through Factorial, which authenticates the person and injects
the trusted context, and an anonymous visitor with the team and process slugs
cannot read the schema or submit it.
factorial.form.publicopts out of that for the forms that genuinely need it. Either way the process behind the form is the guard for what the caller may do (below). - A form opened from inside Factorial is configured in
factorial.form, the Factorial Action block (fcode-factorial-actions).form.enabledstill works and is kept mirrored. A form offered to users on the App's own page isfactorial.form.appTool; the install / settings / uninstall forms are the processes with those reserved slugs (fcode-factorial-actions).factorial.form.publicreleases the form to anyone holding its link, for a form meant for people outside Factorial. - A schema can't carry executable JavaScript.
embedFormOptions.onChangeand fieldtransformFnwere removed, and messages are markdown — raw HTML is never rendered. Client-side behaviour lives in the embedding page. - Never put secrets in embed code or
options— they run in the browser. - Connecting a third-party account (Slack, GitHub, …) is a schema feature —
"ui:widget": "oauth"plus anfcode.oauthflow whose completion redirects to the SDK's callback page. Never ask users to paste an API token into a form when the vendor offers OAuth. See "Connect an external account". - Mapping many Factorial records to another system is a pairing table
(
"ui:field": "pairing"), not a dropdown per record. A row's proposal goes inx-fcode-suggestion, never indefault. See "Pairing tables". - A "Set up with One" button is a
"type": "object"property drawn by"ui:field": "launch-one"that hands the form to One to fill in, never to save. Itspromptandcontextare sent to One: never put secrets in them. See "Set up with One". - Form text is translated with
fcode.i18n("key")tokens in the schema, substituted server-side before the schema is served. Seefcode-i18n. - Form submissions run under a request timeout (about a minute) — keep the synchronous process fast, or run long work asynchronously (see below).
- A fixed wizard across processes is a flow, not a
nextProcessIdchain: declare every step in the entry form'sui:steps(processsteps take slugs) and return nonextProcessIdon the default path. The user can go back and re-submit, so every process in a flow must be safe to re-run. See "Multi-step forms". - Prefer driving UX from the process return value (below); reserve
onSuccess/onErrorfor client-only logic.
Enable a form
- Create the process and define its input parameters (these become the fields).
- Enable the
Formsflag — either in the Trigger from Factorial section of the process Dashboard, or from the CLI workspace inprocesses/<slug>/metadata.json, thenfcode push:
{
"name": "Contact request",
"tags": [],
"factorial": { "enabled": true, "form": { "enabled": true } }
}
The form is one entry point of a Factorial Action — the same factorial
block also holds the button, the Factorial One tool and the backend job
(fcode-factorial-actions, field reference in fcode-cli). The legacy
top-level "form": { "enabled": true } still works and is kept mirrored with
factorial.form.enabled; prefer factorial in new work.
The lifecycle forms of a marketplace app are its install, settings and
uninstall forms: the processes slugged install, settings and uninstall.
A form the App offers its own users, on the App's page in Factorial, is
"factorial": { "form": { "enabled": true, "appTool": true } }. The rules,
including what never to write, are in fcode-factorial-actions.
An install or settings form is re-opened after the app is configured, so it
should show the current values rather than an empty form — the
preRenderProcess pattern for that is in references/advanced.md.
Read submitted values in process code like any parameters:
const { context: { parameters } } = fcode;
What a form may trust
A form is reached through Factorial, which authenticates the person opening it:
the install / settings / uninstall screens, the forms an App offers on its own
page and the UI-trigger dialog (fcode-ui-triggers) all submit through
Factorial's backend, and requiredPolicies is enforced before anything runs
(fcode-factorial-actions). An anonymous visitor holding the team and process
slugs reaches nothing.
Unless the form sets factorial.form.public. That flag releases it to anyone
with the link, and then nothing has authenticated the caller at all: the
company_id and access_id such a submission carries are whatever the page
sent. Turn it on only for a form meant for people outside Factorial, and treat
everything below as the only protection it has.
That settles who is calling. It settles nothing about what they submitted, so the process behind the form is still the guard:
- Treat every submitted parameter as caller-controlled — including the ones
an embedding page pre-filled (
company_id,triggered_from_location,access_id). Never authorize on them. - Return nothing the caller shouldn't already have — the result of a
submission, and a
preRenderProcess'svariables, reach whoever opened the URL. A pre-render has no trusted viewer on a public URL (references/advanced.md"Who is opening the form"). - Keep credentials one-way: a settings form reports only whether a secret
is set, never its value (
references/advanced.md). The platform strips thedefault/examples/constofisSensitivefields from the schema it serves, but a secret put in a label, a markdown block or avariablesnode still reaches the caller.
Embed a form
Two mandatory inputs, both slugs, plus the version pin you should always add:
fcode-team-slug— fromhttps://code.factorialhr.com/platform/<fcode-team-slug>fcode-process-slug— the Slug field on the process Dashboard (e.g.send-welcome-email)- process version — pin it to the
stablealias (next section)
Use the slug, not the process ID. IDs are per-workspace UUIDs, so an
id-based embed breaks when the snippet moves between workspaces; slugs survive
(existing id-based embeds keep working, and the React prop is still named
processId — feed it a slug). Slugs are editable with no redirect for the old
value, so settle them before handing out embed code — renaming one breaks every
embed already pasted into a page.
Load the SDK once (needed for the data-attribute and Fcode.initForm methods):
<script defer src="https://code.factorialhr.com/sdk/forms.js"></script>
Method 1 — data attributes (SDK replaces the element):
<div
data-fcode-form-team="<fcode-team-slug>"
data-fcode-form-process="<fcode-process-slug>"
data-fcode-form-process-version="stable"
></div>
Method 2 — Fcode.initForm (selector or DOM element):
<div id="my-fcode-form"></div>
<script>
Fcode.initForm("#my-fcode-form", {
team: "<fcode-team-slug>",
process: "<fcode-process-slug>",
processVersion: "stable",
});
</script>
Method 3 — FcodeForm React component (React 17/18; install
@factorialco/fcode-react-forms):
import FcodeForm from "@factorialco/fcode-react-forms";
const MyComponent = () => (
<FcodeForm
team={"<fcode-team-slug>"}
processId={"<fcode-process-slug>"}
processVersion={"stable"}
/>
);
In SSR frameworks (e.g. Next.js), import it dynamically with ssr: false.
Pin the form to a version
The version pin (data-fcode-form-process-version / processVersion) takes a
published version tag (v1.0.0) or an alias — use stable, so releases and
rollbacks happen by moving the alias, never by editing the embedded page
(alias model in fcode-core-concepts; release commands in fcode-cli). The
pin applies to both requests the form makes — loading the definition and
submitting it — and the process Dashboard writes it for you: pick a version or
alias in the selector next to the embed code and copy the generated snippet.
An unknown version or alias silently runs the current version — the
platform only logs a server-side warning, same as webhooks (see fcode-cli).
A typo in the attribute is invisible: check the execution's version when a
submission behaves unexpectedly. Direct calls to the form endpoints also accept
the version_tag query parameter documented in fcode-cli.
Handle submission results
Default: a loading overlay shows during execution; on success the form is replaced with a success message, on error an error message.
Callbacks (same shape across methods):
Fcode.initForm("#my-fcode-form", {
team: "<fcode-team-slug>",
process: "<fcode-process-slug>",
onSuccess: (formId, processExecutionResult, formSubmittedData) => {},
onError: (formId, error, formSubmittedData) => {},
});
With data attributes, point to global functions via
data-fcode-form-on-success="HANDLER_NAME",
data-fcode-form-on-next-step="..." and data-fcode-form-on-error="...".
Drive behavior from the process return value (no client code needed):
return { message: "Thanks, **we received your request**." }; // success message (markdown)
return { message: "| Item | Status |\n|---|---|\n| Sync | Done |" }; // GFM tables work too
return { status: 400, body: { formErrors: { // inline validation errors
fields: { email: "Invalid email." }, global: ["A global error."] } } };
return { status: 400, body: { errorMessage: "**Sync failed** — retry." } }; // error message (markdown)
return { redirect: { url: "https://example.com", timeout: 2000 } }; // redirect after submit
Messages are markdown, not HTML. message, errorMessage and a schema's
markdown.before/markdown.after blocks render as GitHub Flavored Markdown —
tables, headings, links, images, code blocks, task lists. Raw HTML is
dropped, never rendered (so nothing authored can execute); put behaviour in
the success / next-step / error callbacks instead.
Keep it fast, or go async
The submission waits for the process to finish, under a request timeout (about a minute). Heavy work done inline — slow API calls, large exports, multi-record syncs — will blow the timeout and fail the submit.
Go async when the work can be slow:
- Embed
async: true— the submission returns201+ an execution ID immediately instead of waiting for the result (seereferences/advanced.md). - Hand off to another process — kick off the heavy work with
fcode.processes.run("process-identifier", options)(seefcode-javascript/fcode-python) and return a quick acknowledgement (message/redirect) rather than awaiting it inline.
Stay synchronous only when the request is genuinely fast, or when data must flow between steps. For passing data, don't block the submit — instead:
preRenderProcesscomputes server-sidevariablesbefore the form renders (seereferences/advanced.md). Opened from Factorial, it can trustfcode.context.factorial(who is looking) to adapt the form, never its parameters; hiding fields is UX only (references/advanced.md"Who is opening the form").- Multi-step forms across processes — a multi-process flow, or
nextProcessIdchaining — carry state forward insteps+variables(below). If the steps are only visual — no work between them — useui:stepsinstead and keep a single process.
Multi-step forms
Three mechanisms, and picking the right one matters:
| Mechanism | Processes | Executions | Use when |
|---|---|---|---|
ui:steps — steps within one form | one | one, after the last step | The split is purely visual; all the logic lives in one process |
Multi-process flow — process steps in ui:steps | one per form | one per form | An intermediate step must execute something (validate externally, store a credential the next form needs) and the steps are known up front |
nextProcessId — chaining | one per form | one per form | Each process decides at run time which form comes next |
They compose: a flow's entry form splits into fields steps, and a chained
process's form can itself declare ui:steps. A wizard whose processes always
return the same fixed nextProcessId is a flow written the hard way — declare
the flow instead, so the user gets one navigation and can go back.
When a form grows long — roughly ten fields or more — split it with
ui:steps, grouping related fields per step with the required ones early.
Steps within a single form (ui:steps)
Declare steps in the schema's root ui node, assigning each property to a step.
The SDK shows one step at a time with a "Next" button; only the last step's
button submits and starts the (single) execution, which receives every collected
parameter exactly as a one-page form would — process code needs no changes.
"ui": {
"ui:steps": {
"config": { "layout": "tabs" },
"steps": [
{ "title": "About you", "description": "Optional text", "fields": ["name"] },
{ "title": "Details", "fields": ["age", "subscribe"] }
]
}
}
config(optional):layout—"tabs"(default) or"sidebar";nextLabel/backLabel— button labels, default"Next"/"Back".ui:submitButtonOptionsapplies to the last step's button.- A step can set its own
nextLabel/backLabel, which win overconfigfor that step ({ "title": "Credentials", "fields": ["apiKey"], "nextLabel": "Verify key" }). On the last step,nextLabelreplaces the submit text. - "Next" validates only the fields on screen (including that step's share of
required); a Back button and the step navigation revisit completed steps without losing input, and unreached steps stay disabled. - Properties not listed in any step are appended to the last one; an unusable
ui:stepsfalls back to the ordinary one-page form with a console warning. - Supports root-level
properties+required+dependencies; root-leveloneOf/allOfcompositions are not split into steps.
Multi-process flows (process steps)
The entry form's ui:steps declares every step of the wizard, including the
forms other processes serve: a step with process: "<slug>" instead of
fields renders that process's whole form. The user sees one navigation for
the whole flow, and the SDK moves from one process to the next on its own.
Worked example — an install form that takes a third-party API key, then maps
teams in a second form whose dropdowns are fetched with that key. The entry
process vendor-setup owns the flow:
{
"title": "Connect Vendor",
"type": "object",
"properties": {
"vendor_api_key": { "title": "Vendor API key", "type": "string", "isSensitive": true }
},
"required": ["vendor_api_key"],
"ui": {
"ui:steps": {
"steps": [
{ "title": "Connect", "description": "Enter your API key", "fields": ["vendor_api_key"] },
{ "title": "Map teams", "description": "Map each Vendor team", "process": "vendor-setup-mapping" }
]
}
}
}
// processes/vendor-setup/index.js — runs when "Connect" is submitted
async function main() {
const { vendor_api_key } = fcode.context.parameters;
const { VendorClient } = fcode.import("vendor-client");
await new VendorClient(vendor_api_key).getTeams(); // throws on a bad key
await fcode.variables.set("VENDOR_API_KEY", vendor_api_key); // overwrite: safe to re-run
return {}; // no nextProcessId: the flow moves on to "Map teams"
}
vendor-setup-mapping's schema sets preRenderProcess, and that pre-render
reads VENDOR_API_KEY to load the vendor's teams into #/variables — it runs
when the "Map teams" form is served, after the key is stored, which a
pre-render on the entry form never could. The full app (Linear, mapping
pre-render, activation, settings, uninstall) is fcode-examples
(references/custom-app-linear.md).
The rules:
-
The entry form owns the flow. Only the first form declares the flow's steps and its
config(layout,nextLabel,backLabel), which applies throughout. A later form's ownprocesssteps andconfigare ignored. -
A
processstep can have sub-steps. When that process's own form declaresui:stepswith two or morefieldssteps, they show one level below the process step in the navigation (2.1,2.2, …) once the form loads. Until then the process step is a single item. They behave like in-form steps: only the last one submits, running the process once. Without its ownui:steps, the process step renders as one page. Use this for a long form served by a later process: the flow keeps one navigation, and the form keeps its steps when it is opened on its own. -
fieldssteps first, at least one of them. They split the entry form and are submitted together to the entry process. Afieldsstep after aprocessstep is dropped with a console warning; with nofieldsstep at all, the wholeui:stepsis ignored and the form renders as a single page. -
processtakes a slug, likenextProcessId. On the marketplace path the platform rewrites the slugs into its own action ids — never write ids. -
Every process in the flow is exposed where the entry form is. Each step loads and submits its own form, so each one needs its form enabled with the same access as the entry. A flow started from a UI trigger needs every step on the same
uiTrigger.locationId, which also shows each step as its own button there. A step that isn't exposed answers not found in the middle of the flow, and the user is left on an error with no way back. -
No
nextProcessIdon the default path. After each successful submit the SDK moves to the next declared step. Every submit button but the last is labelledconfig.nextLabel; the last honoursui:submitButtonOptions. Per-stepnextLabel/backLabelwork onprocesssteps too; when that form has sub-steps,nextLabelgoes on the sub-step that submits it andbackLabelon the first one, whose Back leaves it. -
State carries forward as in a chain: each process receives the earlier forms' data and results in
fcode.context.parameters.steps, and a returnedvariablesnode reaches the following forms. -
Every process in a flow must be safe to re-run. The user can go back to any step already reached; it reopens filled with what was submitted (a process step with sub-steps reopens on its last sub-step), and submitting it again re-runs its process and discards every later step's
stepsentries, data and variables. Overwrite variables and datastore keys rather than appending, and look up webhooks or schedules (or the ids you recorded for them) before creating them. -
Going back drops unsubmitted input, after a confirmation. Leaving a process step for an earlier one, when the user changed a value there (sub-steps included), asks first. Moving between a step's own sub-steps never asks, and values from schema defaults or a pre-render don't count as changes. The wording comes from the entry form's
config:leaveTitle,leaveMessage,leaveConfirmLabel,leaveCancelLabel(English defaults). -
An install flow activates the installation at step 1. When its entry process,
install(fcode-factorial-actions), succeeds, the installation becomesactive, so the later process steps run on an active installation, and a user who abandons the flow there leaves it active. Do the setup the App can't run without in the entry step. -
Factorial One fills in each step of a lifecycle flow as it opens. When One opens an
installorsettingsform in the web chat, eachprocessstep is read only once the user has sent the steps before it, so its pre-render sees what they saved (an API key from step 1 that step 2's pre-render uses to list options, say). The card hands One the step as it read it, so One adds no read of its own; going back to a step reads it again, as for any user, and One reuses its proposal if the step did not change. One reads the conversation, looks up the Factorial data the step needs, and the step opens with its values over the pre-render's; the user reviews and sends it. If One cannot propose values, the step opens as the pre-render built it. Keepuninstallsingle-process: the App is deprovisioned once its uninstall action succeeds, so a flow can't run past its entry step. To make a flow fillable:- Have each step's process store what the next step needs (a team variable
or the datastore) and read it back in the next step's pre-render, as the
Linear setup does with its API key: a pre-render only receives the form's
query-string parameters (
fcode.context.parameters), and thevariablesa step returns resolve the next step's$refs without reaching its pre-render. - Hidden fields are never proposed: they keep their default or the pre-render's value.
- Give options human titles: One picks an option by its meaning and proposes its value.
- Name in a field's title or description the Factorial record it takes ("the Factorial legal entity", "the responsible employee"): One looks it up by that name when the step opens.
- Say in the entry process's
agentTool.descriptionwhat each step holds and what to keep — for example that rows are matched by position, or that a proposed list replaces the step's whole list. One reads only the entry process's contract, and only withagentTool.enabledon; aprocessstep's own contract is not read. Enabling it also makesinstallorsettingsa One tool: the web chat still opens the card, but on clients without it (mobile, external assistants) One may run the process from the chat once the user approves.
- Have each step's process store what the next step needs (a team variable
or the datastore) and read it back in the next step's pre-render, as the
Linear setup does with its API key: a pre-render only receives the form's
query-string parameters (
Overriding the next step. A process may still return nextProcessId:
- naming a later declared step, the flow jumps there and the steps in between show as skipped;
- naming a process the flow doesn't declare, the flow resets: its
navigation and history go away, and that process's form renders on its own,
honouring its own
ui:steps.stepsandvariablesstill carry forward, and the console warns. Treat this as an exit from the wizard, not a branch inside it.
Chaining processes (nextProcessId)
Each form is its own process, and each process names the next form to show by returning its slug — use this when the route is decided at run time, not for a fixed sequence (declare a flow for that):
return { nextProcessId: "collect-shipping-address" };
The field name is still nextProcessId and it accepts a slug or an id — use the
slug, so the same chain works in every workspace.
The SDK then renders the form for nextProcessId. Each later step receives all
previous steps' data and results in fcode.context.parameters under a steps
array. Return a variables node alongside nextProcessId to pass state forward.
A chain has no shared navigation and no way back: each form replaces the last.
Connect an external account (OAuth)
A form can make the user authorize a third-party provider before it is
submitted. Declare a string or boolean property with "ui:widget": "oauth"
(an object property takes "ui:field": "oauth" instead — rjsf never reads
ui:widget on objects):
"github_account": {
"title": "GitHub account",
"description": "You will be asked to authorize in a new window.",
"type": "string",
"ui": {
"ui:widget": "oauth",
"ui:options": {
"authorizationUrl": { "$ref": "#/variables/authorizeUrl" },
"connectLabel": "Connect GitHub",
"connectedLabel": { "$ref": "#/variables/connectedLabel" },
"onComplete": "reload"
}
}
}
The SDK renders a Connect button that opens authorizationUrl in a small
popup, waits for the flow to end, closes the popup and fills the field. The
property's title / description are the message around the button (markdown,
as everywhere; markdown.before/after for longer copy).
ui:options | Default | Purpose |
|---|---|---|
authorizationUrl | — | The platform authorization URL returned by fcode.oauth.start(). Required; an invalid URL disables the button with a console warning |
connectLabel / connectedLabel / pendingLabel | Connect / Connected / Waiting for authorization… | Button text before, after and during the flow |
onComplete | none | What the form does once connected (below) |
popup | { "width": 600, "height": 700 } | Popup size, centred on the page |
closeDelay | 3000 | Milliseconds the popup stays open after finishing, so the user sees the confirmation |
The three rules that make it work:
-
authorizationUrlcomes fromfcode.oauth.start(), called in apreRenderProcess, and is injected with{"$ref": "#/variables/…"}— a plain{{mustache}}token is HTML-escaped (/→/,&→&) and the SDK refuses the URL. Pre-render contract inreferences/advanced.md.const flow = await fcode.oauth.start({ authorizeUrl: "https://github.com/login/oauth/authorize", clientId: fcode.env.GITHUB_CLIENT_ID, scope: ["public_repo"], onComplete: "github-oauth-callback", data: { companyId }, }); return { variables: { authorizeUrl: flow.authorizationUrl } };Never build the authorization URL, the
stateor a PKCE pair by hand. The platform holds all three, plus the oneredirect_uriregistered with the provider — which is the only way this can work at all, since providers require a pre-registered URI and every install is its owndeploy-workspace. -
The completion process needs no webhook. The platform invokes
onCompleteitself once it has verified and spent the state, so there is no endpoint to expose and nothing to authenticate. It arrives withcode,codeVerifier,redirectUri(replay it in the token exchange — providers compare it byte for byte),dataandstate, or witherror/errorDescriptionwhen the provider refused. It exchanges the code, stores the tokens server-side (a sensitive variable, or the datastore with the encrypted flag — seefcode-javascript/fcode-python) and ends by redirecting the popup to the SDK's callback page:const { state } = fcode.context.parameters; return { status: 302, headers: { Location: "https://code.factorialhr.com/sdk/oauth-callback.html" + "?status=success&value=" + encodeURIComponent(login) + "&state=" + encodeURIComponent(state), }, };That page tells the form how it went — the form only trusts a message from the very window it opened — then closes itself. Query parameters:
status(success; anything else counts as an error),value(becomes the field value),state(required, echoed from the callback parameters),message(shown under the button on error), plus any extra parameter anobjectfield should receive.Echo
stateon every exit, the error ones included. It is what binds the outcome to the popup the form opened, and a completion that omits it is discarded when it arrives over the fallback channel — the COOP-severed caseonComplete: "reload"exists to recover. The flow then ends as cancelled even though the token exchange succeeded and the token was stored. -
valueis an opaque handle (an account login, a connection id) — never a token: it reaches the browser and travels in the submission. The connected state is a signal for the user, not a proof: the process receiving the submission must verify the connection on its side.
Field value. boolean → true; string → the value parameter;
object → every parameter except status / message. Empty until connected,
so marking the field required keeps the form from being submitted before the
account is connected. Closing the popup early counts as cancelled and re-enables
the button. An error shows its message under the button and reloads the
form definition, whatever onComplete says: the callback has run and may have
consumed the one-time state in the authorization URL, so only a fresh
preRenderProcess run can put a working URL behind the button. Typed values and
the message survive the reload, nothing is submitted, and the user simply
retries. A reload that fails leaves the form as it was.
A default renders the button connected. The button is in its connected
state whenever the field has a value, so a preRenderProcess that finds an
existing connection returns the property with a default set to the connection
handle — the button renders as connected (disabled) and the handle travels with
the submission like any other default. This is how a returning user, a
connection finished after the popup was closed, or an onComplete: "reload"
lands on the connected view; a value arriving this way also clears an earlier
error message.
onComplete — what happens once connected:
none— the button shows its connected state; the user submits as usual and the process receives the value with the other parameters.submit— the form is submitted immediately, so the return value'smessage/redirect/nextProcessIdapply right away. In aui:stepsform this advances to the next step.reload— the form fetches its definition again, re-running thepreRenderProcess, so the server can check the connection and render the connected state (different copy, more fields, adefaultthat turns the button into "Connected as …"). Values typed into other fields are kept. Because the server is the source of truth here, the form also reloads when the popup is closed without reaching the callback page — the only mode that reloads on cancel, since the callback never ran and the URL is still good.
Limits worth knowing: the popup is opened from the click itself, so default
popup blockers let it through — a browser set to block all pop-ups gets a
message under the button instead; a Cross-Origin-Opener-Policy header on the
embedding page or the provider can sever the link with the popup, in which case
the flow ends as cancelled and onComplete: "reload" is the recovery path.
A complete sample — pre-render starting the flow, the completion process, the form
process verifying the connection — is in fcode-examples
(references/oauth-connect.md).
Pairing tables
Integrations map Factorial records to their counterparts elsewhere: expense
accounts to a NetSuite chart of accounts, payroll concepts to DATEV wage types,
absence types to an official code list. One dropdown per record turns hundreds
of records into a form nobody can review. Mark the section
"ui:field": "pairing" and Factorial draws it as one table: per row the
Factorial record, a searchable picker of the other system's records (a text
input where they can't be listed, see "Typed rows" below), and a
status — Confirmed (has a value, including an explicit "Not mapped"),
Suggested (the picker shows the proposal, marked as not chosen yet; the
app's reason on hover), No longer available (the stored pair is no longer a
choice) or Needs a choice — plus, above the table, Accept N suggestions
and a Needs a choice (N) filter that narrows the list to the open rows (a
row paired meanwhile stays listed until the filter is turned off), and
Accept on each row showing a suggestion.
"accounts": {
"type": "object",
"title": "Expense accounts",
"ui": {
"ui:field": "pairing",
"ui:options": {
"columns": ["Factorial", "NetSuite"],
"inUseNote": "Only the accounts your expense categories use are listed.",
"labels": { "addRow": "Add account" }
}
},
"x-fcode-choices": [
{ "const": "", "title": "Not mapped" },
{ "const": "6100", "title": "6100 · Travel" },
{ "const": "6200", "title": "6200 · Meals" }
],
"properties": {
"acc_12": { "type": "string", "title": "Travel", "default": "6100" },
"acc_13": {
"type": "string",
"title": "Meals",
"x-fcode-suggestion": { "value": "6200", "reason": "Same name" },
"x-fcode-in-use": true
}
}
}
The contract:
-
One property per row. The property name is the key the submission carries (use the Factorial record's id, prefixed so it is a valid key:
acc_12),titleis the Factorial side. A property that is not astringis left out of the table with a console warning. The section may be marked on its ownuior from the rootui/uiSchemamap by name. -
Choices once per section.
x-fcode-choices(a list of{ const, title }) on the section is used by every row without its ownoneOf/enum. Repeating a long list on every row makes the schema grow with rows × records; a row that needs a different list keeps its own. -
defaultis the stored pair and shows as Confirmed. A stored pair that is no longer among the choices (deleted or deactivated on the other side) is set aside: the row reads No longer available: <value>, needs a new choice, and the old value is not submitted. -
x-fcode-suggestion: { value, reason }is a proposal, never submitted until the user accepts it or picks another record: saving without accepting leaves the row unpaired. Clearing a row dismisses its suggestion. Avaluethat is not one of the row's choices is ignored (on a typed row any text goes). Leave itssourceout: your app's suggestions are"app", and"one"marks One's (see "Set up with One"). -
Typed rows, when the other system can't be listed. A section that sets
"ui:options": { "freeText": true }types its rows: there, a string row with nooneOf, noenumand no sectionx-fcode-choicesis a text input, the admin types the other system's value into a text input, and the submission carries what was typed. WithoutfreeText, a row with no choices is left out of the table (with a console warning), so a pre-render that fails to fetch the vendor's list gives an empty table, not silent free text. Opt in only when the vendor has no API to list the records or the app has no access to it — don't invent a fake choice list. It reads Needs a value (not Needs a choice) until something is typed, then Confirmed; blanking it clears the row. When every row of a section is typed, the filter reads Needs a value (N). Suggestions anddefaultwork as on any row. Typed rows have no "Not mapped" and never read No longer available. Since anything can be typed, constrain the row (pattern,maxLength: the error shows on that row) and check the values again in the process. In an opted-in section, rows with choices stay selects, so typed rows and rows with choices mix.freeTextmust be a boolean; anything else warns and counts as off."codes": { "type": "object", "title": "Wage type codes", "ui": { "ui:field": "pairing", "ui:options": { "freeText": true, "columns": ["Factorial", "Payroll code"] } }, "properties": { "concept_4": { "type": "string", "title": "Base salary", "pattern": "^[0-9]{4}$", "default": "1000" }, "concept_7": { "type": "string", "title": "Overtime", "pattern": "^[0-9]{4}$" } } } -
x-fcode-in-use: truemarks Factorial records in use. While any row is marked, the table lists only those plus rows paired or suggested, and Add row brings in any other row. Mark them on long lists: each edit re-renders every listed row, and a few hundred listed rows make every change lag noticeably. -
"Not mapped" is an explicit choice. A
""choice is offered in the picker under its own title; picking it submits"". A stored""is Confirmed and a suggestion never replaces it, so only send"default": ""when the admin chose "not mapped" (not as a blank for every row). This holds only when the row's choices include a""option: without one, a stored""is dropped, the row reads Needs a choice, and the next save leaves the key out. Clearing a row (✕) leaves its key out of the submission. -
Submission is the same flat
{ "acc_12": "6100", … }object a section of ordinary dropdowns submits, so the handler reads it as it always did; the process must still check every value against the other system's records (parameters are untrusted, §What a form may trust). -
ui:options(all optional):columns(two headers),inUseNote, andlabelsoverriding the table text —status,confirmed,suggested,suggestedByOne,oneSuggests({value}),use,needsChoice,needsValue,unavailable({value}),accept,acceptAll({count}),summary({confirmed},{toReview}),placeholder,addRow,needsChoiceFilter({count}),needsValueFilter({count}),empty. Translate them withfcode.i18ntokens (fcode-i18n). A bad option falls back to its default with a console warning. -
Validation works per row: a row listed in the section's
requiredmust be paired, and the error shows on that row, which is always listed, even when the in-use list or the filter would leave it out.
Build the section in a preRenderProcess (references/advanced.md): rows from
the Factorial records, x-fcode-choices from the other system, default from
what the app stored, x-fcode-suggestion from the app's own matching (same
number, same name…), x-fcode-in-use from what Factorial actually uses. Inject
the whole section as one variable
("accounts": { "$ref": "#/variables/accountsField" }).
The table is drawn inside Factorial. The hosted forms.js and any host without
the f0 theme render the same section as ordinary dropdowns (text inputs for
typed rows), which submit the same values. A complete app — pre-render building the section, settings process
storing the pairs — is in fcode-examples (references/pairing-table.md).
A host on an old forms SDK (@factorialco/fcode-react-forms 3.7 or earlier)
doesn't know the pairing contract: rows that rely on x-fcode-choices render as
free text, and rows with their own oneOf are pre-filled with its first choice,
so don't ship a pairing section to such a host.
Set up with One
A long setup, or a pairing table with hundreds of rows, can be handed to One
(Factorial's AI assistant) from the form itself. Add a "type": "object"
property drawn by "ui:field": "launch-one": it shows only the button, submits
nothing, and inside Factorial opens a new conversation with One about this form.
"setupWithOne": {
"type": "object",
"ui": {
"ui:field": "launch-one",
"ui:options": {
"label": "Set up with One",
"prompt": "Set up the NetSuite integration",
"context": "The subsidiary chosen so far: \"{{subsidiary}}\". Use the subsidiary of the company's main legal entity. Match accounts by number first, then by meaning; never pick a parent account."
}
}
}
-
Add it only where One can work the values out: records to match by meaning (a mapping, a pairing table), values in the company's own data or documents (a policy, the handbook), or a setup the
contextcan describe in words. Leave it off a form only the admin can answer (credentials, choices that are theirs to make) and off a short form that is quicker to fill in by hand: a button that leaves most fields empty costs the admin more than it saves. -
When the values live in another system, have One ask for them. A form may need identifiers or codes that only another tool holds, so One cannot find them in Factorial. If that tool can export them (a CSV) or show them on one screen (a screenshot), the
contexttells One to ask the admin for exactly that export, then fill the form in from it: name the export or screen as the other tool calls it, and say which column or label goes to which field. One asks in the conversation, reads the file the admin attaches and proposes the values. What it read reaches the form as part of a short note (about 8,000 characters), so this suits dozens of rows, not thousands: for those, have the app read the other system itself and fill a pairing table."context": "The NetSuite internal ids of the subsidiaries are not in Factorial. Ask the admin for the CSV export of Setup > Company > Subsidiaries in NetSuite (or a screenshot of that list), then fill in each subsidiary's internal id from its Internal ID column, matching rows by name." -
label(required) is the button text andprompt(required) the short message shown in the conversation as the user's.contextis longer instructions sent along unseen: how this app is set up, what to match by, what to leave alone.sectionnames the field or pairing section One works on; without it, the whole form. A form may have several buttons, for example one per pairing table with its ownsection, placed where it should appear. -
collapse: true(off by default, and only withsection) moves the button into that section, right after its title and description, and starts the section's content collapsed under a "Show the full form" toggle beside it. Collapsed fields stay in the form: they keep their values, validate and are saved, and one with an error opens. Secret, file and hidden fields never collapse. Change the toggle's text withlabels.showFormandlabels.hideForm. Without asection,collapseis ignored with a console warning; where the button isn't shown, nothing collapses. -
{{field}}and{{variable}}inpromptandcontextare filled in from the form's current values when the user clicks. Only plain names, no Mustache sections. Secret, file and hidden fields (and anything holding one), and variables that only feed secret fields, are filled in as empty. -
What One does. It reads the form as it stands, with the user's edits, and proposes: values for the fields the user has not changed, and a suggestion with a reason for each open pairing row, marked Suggested by One. On a confirmed row it disagrees with, the pair stays and the row offers One suggests X with Use. It never fills a secret, file or hidden field, never touches a field the user changed or a row they dismissed, and never saves the form or runs the process: the user reviews and saves. After the save, One reports the result in the same conversation.
-
What One knows of your app is the button's texts and the form's titles, descriptions and choices. Write
contextfor a person setting the app up for the first time. The user's company data One looks up itself. -
Never put secrets in
promptorcontext: they go to One. Do not ask One to choose notification recipients or to tick confirmations for the user; it won't. -
Where the button shows is the host's decision: on forms opened from Factorial (Integrations, the App's page, trigger forms) for users and companies with One. It renders nothing in the form card One itself shows in a conversation, in the hosted
forms.js, and in any host that doesn't offer One, so the schema stays valid everywhere.
A complete sample, with a button for a pairing table, is in fcode-examples (references/pairing-table.md).
Automatic file uploads
A file field is "type": "string" with a "ui": { "ui:widget": "file" } key
inside the property:
{
"properties": {
"inputFile": { "type": "string", "ui": { "ui:widget": "file" } }
}
}
(A root-level ui map keyed by field name — rjsf's uiSchema convention — is
also merged, but per-property ui is the documented form; the root ui is
mainly for form-level options like ui:submitButtonOptions. For secret inputs
use "isSensitive": true on the property — it renders a password widget
automatically, while "ui:widget": "password" alone only hides the value and
the CLI warns about it on push; see fcode-json-schema.)
On submit the file is uploaded to Storage before the process starts, and the
parameter arrives as an fcode.storage://… reference (an array if multiple
files allowed). Strip the prefix to download:
const { context: { parameters } } = fcode;
const stream = await fcode.storage.download(
parameters.inputFile.replace("fcode.storage://", "")
);
Uploaded files count toward storage limits (1,000 files, 50 MB each —
fcode-core-concepts › Plans & limits) — delete them at the end of the process
if only needed transiently.
Advanced
For styling and the two themes (including the f0 theme to use when embedding in a
React app inside Factorial), markdown message rendering with f0 components
(markdownComponents), initial/hidden values, async submission, custom
headers, API-host override, variables replacement, pre-rendering current values
into install/settings forms, reacting to user input from your own page (the
React onChange prop, the fcode-forms-* DOM events), and modal rendering,
read references/advanced.md.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/factorialco/factorial-code-skills/fcode-forms">View fcode-forms on skillZs</a>