Factorial Code — platform guide (AMA)
Factorial Code (fcode) is Factorial's platform for building apps and
automations against the Factorial Public API. This skill covers using the
platform — the journey from requesting access to a published marketplace
app — and how to behave when supporting users through it. For building the
app itself (processes, modules, CLI, forms), route to the owning skills
(see the routing table below).
The full stage-by-stage walkthrough is in references/journey.md; common
problems and fixes are in references/troubleshooting.md.
Who you're helping
Three user roles use the platform. Establish which one you're talking to
early — several flows diverge by role:
| Role |
Who |
Key differences |
| Factorial internal |
Developers at Factorial |
Create their own OAuth apps in the Factorial Backoffice; create demo companies directly (using the Demo generator); Slack #factorial-code-users available |
| Partner |
External companies building apps/integrations with Factorial |
OAuth app preconfigured by an administrator; demo companies by request |
| Individual Contributor |
Someone building their own app or automation (may be a customer, but not always — never call this role "end customer") |
Same as Partner |
All roles talk to Factorial through the Public API, and all belong to a
development team: every app a team creates is shared by all its members.
When someone requests access and an administrator sees their organization
already has a team on the platform, they are added to that existing team.
Support-agent behavior rules
- Answer only from documented flows — this skill, its references, the
other
fcode-* skills, and the public docs. Never invent UI elements,
URLs, commands, or policies. If it isn't covered, say so and escalate.
- Identify the user's role first when the answer differs by role.
- Describe flows by page and section name (e.g. "the Getting started
checklist on the App detail page"), not by exact button pixels — labels
change; flows are stable.
- Admin actions: outcome only. When a step is performed by an
administrator (access approval, demo provisioning, OAuth preconfiguration,
release review), tell the user what they will observe and what to do next.
Never describe admin-side mechanics or how credentials are delivered.
- Answer in the user's language.
- Fetch before deep-diving. When you have web access, read the linked
docs page before answering a detailed question; the live docs win over
this skill on details. Without web access, answer from this skill and say
which docs page has more.
- Escalate when needed — an admin action, a stuck request, or an
uncovered question. Escalation paths are in the last section.
Platform map
Everything lives under https://code.factorialhr.com, split across three
surfaces users often conflate:
- Docs (
/docs/...) — public documentation, plus the landing page with
the request-access form.
- App console (
/dashboard/...) — apps, teams, demo companies,
marketplaces, installations. Where the journey below happens.
- Workspace console (
/platform/...) — inside a workspace: processes,
executions, schedules, variables, versions, API credentials. The app
console links into it — every such jump is labelled "Open on platform";
for a deploy- (installation) workspace it lands on the executions page.
App console areas (the sidebar groups them into Build, Operate, and
Admin sections):
| Area |
What it's for |
| Apps |
The team's apps; where a new app is created |
| App detail page |
Per-app home: the Getting started checklist and the Development / Production / Publication / README tabs |
| App settings |
Configuration (marketplace visibility, lifecycle) and OAuth (requested scopes plus the development and production credentials) |
| Demo companies |
Demo Factorial companies for testing installs |
| Test marketplace |
Simulation of the production marketplace, run against demo companies |
Plus the self-describing Marketplace, Team, and Installations areas.
The journey at a glance
| # |
Stage |
Where |
What happens |
| 1 |
Request access |
Landing page → request-access form |
An administrator reviews it and you're notified; joins an existing development team when one matches |
| 2 |
Create an App |
Apps → create |
Name and purpose; language (JavaScript or Python); OAuth scopes; the integrations framework opt-in (decision rule in references/journey.md) |
| 3 |
Getting started |
App detail page checklist |
Ordered setup steps: build locally, link the Factorial integration (framework apps only), configure OAuth (when scopes were requested), publish a release, add marketplace metadata |
| 4 |
Configure OAuth |
App settings → OAuth tab |
Per-environment client credentials for the OAuth flow (per-role setup in references/journey.md) |
| 5 |
Build locally |
Your machine |
Install the CLI, fcode clone the dev workspace (or fcode team:clone for every App of your team at once), code with your own agent + the fcode-* skills, test locally, fcode push |
| 6 |
Demo company |
Demo companies page |
Internal: create directly. Partner/IC: request one; you're notified by email |
| 7 |
Test installs |
Test marketplace |
Run the real OAuth flow with the demo company's credentials, install, exercise the appRole forms and any UI trigger buttons inside the demo company's Factorial |
| 8 |
Release |
App detail → Production tab |
Request a release (semver + notes); after validation it's promoted to the prod workspace — self-service for a Factorial admin of the owning team, by an operator otherwise (references/journey.md §8) |
| 9 |
Publish listing |
App detail → Publication tab |
Marketplace listing metadata: a linked DatoCMS record and/or the fallback fields |
| 10 |
Production |
Marketplace |
Visible and installable; each install gets its own isolated workspace |
Per-stage detail, per-role callouts, and lifecycle states: references/journey.md.
Workspaces behind the journey
Naming caution: a Factorial Code workspace is also called a "team" in the
workspace console, in the platform API, and in a few CLI surfaces ("team
variables", the parentTeams field) — that sense is unrelated to the
development team of humans described above. The CLI's fcode team:* commands
mean the development team: they operate on every App it owns (see fcode-cli).
Each app maps to workspaces (slugs carry an encoded token, not the raw id):
dev-{appId} — the development workspace you clone and push to.prod-{appId} — production copy, created when the first release is
requested. Treat its code as read-only — changes belong in dev and reach it
through the release flow; only operators and the app's Factorial team
admins can write to it at all. Its variables are live — shared defaults
and credentials for all installations are managed there.deploy-{installationId} — one per company installation, inheriting from
the app workspace: it holds only that company's variables and executions,
fully isolated from other companies. A change in the parent workspace is
automatically available in every installation workspace.base-app / base-integration-app (language-matched variants, -js/-py)
— shared bases every app inherits: API clients, webhook/schedule/email/form
helpers, and (for framework apps) the integration templates.
Released versions are pinned tags and the stable alias points at the
current one (model in fcode-core-concepts). For a marketplace app, ship
through the release flow (stage 8) — don't publish versions or move stable
by hand.
Buttons inside Factorial — UI triggers
Besides forms and webhooks, an installed app can put its own buttons on
Factorial's pages. Factorial teams declare locations in the product (a page
header, an actions dropdown — e.g. calendar.header.admin); an app process
that declares a uiTrigger for that location shows up there as a button, with
the app's label and icon, for every company that installed the app. Clicking it
runs the process with the page's context (the record on screen, the company),
or opens the process's form when it has one — so a "Sync to Acme" action can
live next to Factorial's native actions without Factorial shipping any
integration-specific UI.
What to tell users:
- It works only for installed marketplace apps — the buttons are read from
the company's
deploy- workspace, so a trigger reaches customers through the
release flow (stage 8) like any other change; in development, the demo company
shows the dev workspace's triggers (stage 7).
- The location id comes from Factorial: there is no catalogue in the
platform. A developer who wants a button on a page that has no location yet
needs the owning Factorial team to add one — escalate as a product request.
- Some locations admit one app at a time; installing a second app that
claims such a location fails with a message naming the first.
- Configuration lives on the process page (Triggered from Factorial UI) or
in
metadata.json; the developer-facing rules are in fcode-ui-triggers.
Routing — where deep questions live
| Question is about |
Route to |
Platform model: processes, modules, variables & inheritance, datastore/storage, versioning & stable |
fcode-core-concepts |
CLI commands, metadata.json / settings.json fields, appRole field reference, webhook auth, FACTORIAL_TOKEN |
fcode-cli — docs: /docs/cli/ |
| Writing process/module code |
fcode-javascript / fcode-python — docs: /docs/processes/ |
| Input-parameter schemas (forms definition) |
fcode-json-schema |
| Embedding forms on webpages, themes, pre-fill |
fcode-forms — docs: /docs/forms/ |
Buttons inside Factorial (uiTrigger, locations, result envelope) |
fcode-ui-triggers |
| Recommended agent working method, MCP tools |
fcode-agent — docs: /docs/mcp-server/ |
| Worked examples (integration, install/uninstall lifecycle) |
fcode-examples |
| Executions, schedules, webhooks at runtime |
docs: /docs/executions/ |
| Integrations framework |
docs: /docs/building-apps/integrations-framework/ |
| OAuth & API tokens |
docs: /docs/building-apps/oauth/ |
| Workspace hierarchy |
docs: /docs/building-apps/workspaces/ |
| Roles & permissions: who can read/write/promote per workspace |
references/journey.md §8 — docs: /docs/building-apps/permissions/ |
| The end-to-end journey (public version) |
docs: /docs/building-apps/developer-journey/ |
Doc paths are relative to https://code.factorialhr.com.
Escalation & admin actions
| Need |
What to do |
| Access request pending |
It's under review; you'll be notified of the outcome |
| OAuth app for a Partner / Individual Contributor |
Preconfigured by an administrator — visible on the App settings' OAuth tab once done |
| Demo company (Partner / IC) |
"Request a demo company" on the Demo companies page; you're emailed when it's ready |
| Release review outcome |
The release either deploys or you're notified of required changes; fix and request again with a higher version |
| Promote a release to production |
A Factorial admin of the owning team does it themselves (the App detail page's "How to promote" dialog has the commands); everyone else's route is an operator — references/journey.md §8 |
| Private app installed for a specific company |
A production installation created from the App detail page — by an administrator or by a developer who provides the Factorial company ID (e.g. how Factorial's Forward Deployed Engineers roll out private apps) |
| Anything not covered |
Internal Factorial users: Slack #factorial-code-users. Others: the in-platform request flows above |
1---2name: fcode-ama3description: Factorial Code platform user journey and support — from requesting access through app creation, OAuth setup, demo companies and the Test marketplace to releases and marketplace publication. Use when answering "how do I…" questions about using the platform, guiding a user through any journey stage, or acting as a Factorial Code support agent.4license: MIT5---67# Factorial Code — platform guide (AMA)89Factorial Code (fcode) is Factorial's platform for building apps and10automations against the Factorial Public API. This skill covers **using the11platform** — the journey from requesting access to a published marketplace12app — and how to behave when supporting users through it. For *building* the13app itself (processes, modules, CLI, forms), route to the owning skills14(see the routing table below).1516The full stage-by-stage walkthrough is in `references/journey.md`; common17problems and fixes are in `references/troubleshooting.md`.1819## Who you're helping2021Three user roles use the platform. Establish which one you're talking to22early — several flows diverge by role:2324| Role | Who | Key differences |25|---|---|---|26| **Factorial internal** | Developers at Factorial | Create their own OAuth apps in the **Factorial Backoffice**; create demo companies directly (using the Demo generator); Slack `#factorial-code-users` available |27| **Partner** | External companies building apps/integrations with Factorial | OAuth app preconfigured by an administrator; demo companies by request |28| **Individual Contributor** | Someone building their own app or automation (may be a customer, but not always — never call this role "end customer") | Same as Partner |2930All roles talk to Factorial through the **Public API**, and all belong to a31**development team**: every app a team creates is shared by all its members.32When someone requests access and an administrator sees their organization33already has a team on the platform, they are added to that existing team.3435## Support-agent behavior rules3637- **Answer only from documented flows** — this skill, its references, the38 other `fcode-*` skills, and the public docs. Never invent UI elements,39 URLs, commands, or policies. If it isn't covered, say so and escalate.40- **Identify the user's role first** when the answer differs by role.41- **Describe flows by page and section name** (e.g. "the Getting started42 checklist on the App detail page"), not by exact button pixels — labels43 change; flows are stable.44- **Admin actions: outcome only.** When a step is performed by an45 administrator (access approval, demo provisioning, OAuth preconfiguration,46 release review), tell the user what they will observe and what to do next.47 Never describe admin-side mechanics or how credentials are delivered.48- **Answer in the user's language.**49- **Fetch before deep-diving.** When you have web access, read the linked50 docs page before answering a detailed question; the live docs win over51 this skill on details. Without web access, answer from this skill and say52 which docs page has more.53- **Escalate when needed** — an admin action, a stuck request, or an54 uncovered question. Escalation paths are in the last section.5556## Platform map5758Everything lives under `https://code.factorialhr.com`, split across three59surfaces users often conflate:6061- **Docs** (`/docs/...`) — public documentation, plus the landing page with62 the request-access form.63- **App console** (`/dashboard/...`) — apps, teams, demo companies,64 marketplaces, installations. Where the journey below happens.65- **Workspace console** (`/platform/...`) — inside a workspace: processes,66 executions, schedules, variables, versions, API credentials. The app67 console links into it — every such jump is labelled **"Open on platform"**;68 for a `deploy-` (installation) workspace it lands on the executions page.6970App console areas (the sidebar groups them into **Build**, **Operate**, and71**Admin** sections):7273| Area | What it's for |74|---|---|75| **Apps** | The team's apps; where a new app is created |76| **App detail page** | Per-app home: the Getting started checklist and the **Development / Production / Publication / README** tabs |77| **App settings** | **Configuration** (marketplace visibility, lifecycle) and **OAuth** (requested scopes plus the development and production credentials) |78| **Demo companies** | Demo Factorial companies for testing installs |79| **Test marketplace** | Simulation of the production marketplace, run against demo companies |8081Plus the self-describing **Marketplace**, **Team**, and **Installations** areas.8283## The journey at a glance8485| # | Stage | Where | What happens |86|---|---|---|---|87| 1 | Request access | Landing page → request-access form | An administrator reviews it and you're notified; joins an existing development team when one matches |88| 2 | Create an App | Apps → create | Name and purpose; language (**JavaScript** or **Python**); **OAuth scopes**; the **integrations framework** opt-in (decision rule in `references/journey.md`) |89| 3 | Getting started | App detail page checklist | Ordered setup steps: build locally, link the Factorial integration (framework apps only), configure OAuth (when scopes were requested), publish a release, add marketplace metadata |90| 4 | Configure OAuth | App settings → OAuth tab | Per-environment client credentials for the OAuth flow (per-role setup in `references/journey.md`) |91| 5 | Build locally | Your machine | Install the CLI, `fcode clone` the dev workspace (or `fcode team:clone` for every App of your team at once), code with your own agent + the `fcode-*` skills, test locally, `fcode push` |92| 6 | Demo company | Demo companies page | Internal: create directly. Partner/IC: request one; you're notified by email |93| 7 | Test installs | Test marketplace | Run the real OAuth flow with the demo company's credentials, install, exercise the `appRole` forms and any UI trigger buttons inside the demo company's Factorial |94| 8 | Release | App detail → Production tab | Request a release (semver + notes); after validation it's promoted to the prod workspace — self-service for a Factorial admin of the owning team, by an operator otherwise (`references/journey.md` §8) |95| 9 | Publish listing | App detail → Publication tab | Marketplace listing metadata: a linked DatoCMS record and/or the fallback fields |96| 10 | Production | Marketplace | Visible and installable; each install gets its own isolated workspace |9798Per-stage detail, per-role callouts, and lifecycle states: `references/journey.md`.99100## Workspaces behind the journey101102Naming caution: a Factorial Code **workspace** is also called a "team" in the103workspace console, in the platform API, and in a few CLI surfaces ("team104variables", the `parentTeams` field) — that sense is unrelated to the105**development team** of humans described above. The CLI's `fcode team:*` commands106mean the development team: they operate on every App it owns (see `fcode-cli`).107108Each app maps to workspaces (slugs carry an encoded token, not the raw id):109110- `dev-{appId}` — the development workspace you clone and push to.111- `prod-{appId}` — production copy, created when the first release is112 requested. Treat its code as read-only — changes belong in dev and reach it113 through the release flow; only operators and the app's Factorial team114 admins can write to it at all. Its variables are live — shared defaults115 and credentials for all installations are managed there.116- `deploy-{installationId}` — one per company installation, inheriting from117 the app workspace: it holds only that company's variables and executions,118 fully isolated from other companies. A change in the parent workspace is119 automatically available in every installation workspace.120- `base-app` / `base-integration-app` (language-matched variants, `-js`/`-py`)121 — shared bases every app inherits: API clients, webhook/schedule/email/form122 helpers, and (for framework apps) the integration templates.123124Released versions are pinned tags and the **`stable` alias** points at the125current one (model in `fcode-core-concepts`). For a marketplace app, ship126through the release flow (stage 8) — don't publish versions or move `stable`127by hand.128129## Buttons inside Factorial — UI triggers130131Besides forms and webhooks, an installed app can put **its own buttons on132Factorial's pages**. Factorial teams declare *locations* in the product (a page133header, an actions dropdown — e.g. `calendar.header.admin`); an app process134that declares a `uiTrigger` for that location shows up there as a button, with135the app's label and icon, for every company that installed the app. Clicking it136runs the process with the page's context (the record on screen, the company),137or opens the process's form when it has one — so a "Sync to Acme" action can138live next to Factorial's native actions without Factorial shipping any139integration-specific UI.140141What to tell users:142143- It works only for **installed marketplace apps** — the buttons are read from144 the company's `deploy-` workspace, so a trigger reaches customers through the145 release flow (stage 8) like any other change; in development, the demo company146 shows the dev workspace's triggers (stage 7).147- The **location id comes from Factorial**: there is no catalogue in the148 platform. A developer who wants a button on a page that has no location yet149 needs the owning Factorial team to add one — escalate as a product request.150- Some locations admit **one app at a time**; installing a second app that151 claims such a location fails with a message naming the first.152- Configuration lives on the process page (**Triggered from Factorial UI**) or153 in `metadata.json`; the developer-facing rules are in `fcode-ui-triggers`.154155## Routing — where deep questions live156157| Question is about | Route to |158|---|---|159| Platform model: processes, modules, variables & inheritance, datastore/storage, versioning & `stable` | `fcode-core-concepts` |160| CLI commands, `metadata.json` / `settings.json` fields, `appRole` field reference, webhook auth, `FACTORIAL_TOKEN` | `fcode-cli` — docs: `/docs/cli/` |161| Writing process/module code | `fcode-javascript` / `fcode-python` — docs: `/docs/processes/` |162| Input-parameter schemas (forms definition) | `fcode-json-schema` |163| Embedding forms on webpages, themes, pre-fill | `fcode-forms` — docs: `/docs/forms/` |164| Buttons inside Factorial (`uiTrigger`, locations, result envelope) | `fcode-ui-triggers` |165| Recommended agent working method, MCP tools | `fcode-agent` — docs: `/docs/mcp-server/` |166| Worked examples (integration, install/uninstall lifecycle) | `fcode-examples` |167| Executions, schedules, webhooks at runtime | docs: `/docs/executions/` |168| Integrations framework | docs: `/docs/building-apps/integrations-framework/` |169| OAuth & API tokens | docs: `/docs/building-apps/oauth/` |170| Workspace hierarchy | docs: `/docs/building-apps/workspaces/` |171| Roles & permissions: who can read/write/promote per workspace | `references/journey.md` §8 — docs: `/docs/building-apps/permissions/` |172| The end-to-end journey (public version) | docs: `/docs/building-apps/developer-journey/` |173174Doc paths are relative to `https://code.factorialhr.com`.175176## Escalation & admin actions177178| Need | What to do |179|---|---|180| Access request pending | It's under review; you'll be notified of the outcome |181| OAuth app for a Partner / Individual Contributor | Preconfigured by an administrator — visible on the App settings' OAuth tab once done |182| Demo company (Partner / IC) | "Request a demo company" on the Demo companies page; you're emailed when it's ready |183| Release review outcome | The release either deploys or you're notified of required changes; fix and request again with a higher version |184| Promote a release to production | A Factorial admin of the owning team does it themselves (the App detail page's "How to promote" dialog has the commands); everyone else's route is an operator — `references/journey.md` §8 |185| Private app installed for a specific company | A production installation created from the App detail page — by an administrator **or by a developer** who provides the Factorial company ID (e.g. how Factorial's Forward Deployed Engineers roll out private apps) |186| Anything not covered | Internal Factorial users: Slack `#factorial-code-users`. Others: the in-platform request flows above |
factorialco