Flows for your clients
If you run fulfillment or integrations for other businesses through the embed, you can build a flow once as a template and install it for each client with that client's own settings. Every installed copy runs on the client's behalf, touches only the client's data, and shows up in the client's white-label portal.
The Templates and Clients tabs appear in Flows for members with the
embed.manage permission.
Create a template
On the Templates tab, click Create template. Give it a Name, a Trigger, and an optional Description. The template page has two parts:
- Settings: the Name, Description, Trigger configuration, and Params schema (JSON). Click Save settings to store them.
- The designer: the same canvas, palette, and property panel you use for flows (see Build a flow). Test is turned off here because a template has no live data; install it to test it.
Parameters
The Params schema is a JSON Schema describing the settings each client's copy needs, such as a carrier or a warehouse code:
{
"type": "object",
"required": ["carrier"],
"properties": {
"carrier": { "type": "string" }
}
}
The Install form preview shows the form your team will fill in for each
install. Inside the template, read the values with references such as
{{ params.carrier }}. Params are checked against the schema at install and
again at every upgrade, and can be up to 16 KB.
Publish a template
Click Publish in the designer. The dialog (Publish v2?, for example) explains the version change and lists any problems that block it. Each publish increases the template's version number. Only published templates can be installed.
On a published template the save button reads Save (live now): new installs and upgrades copy the template's saved definition right away. Publishing records that definition as the next version number. Flows already installed keep running their own copy until you upgrade them.
Archive retires a template: it can no longer be edited, published, or installed, and flows already installed from it keep running.
Install a template for a client
Install from the Templates tab (Install on a template's row) or from the Clients tab (Install template on a client's card). The Install template dialog asks for:
- Template: any published template.
- Client: the client the flow runs for, or No client (your organization).
- Flow name and an optional Slug (generated from the name if blank).
- Parameters: the form generated from the params schema.
- Client can run this flow: lets the client start runs from their own portal.
- Override trigger configuration: for bridge-event templates, pick the client's own bridge and events. This is required when installing for a client, because a client's flow cannot listen to your organization's bridge.
The install creates a flow with the template's definition as its draft. Publish it to start running: open the new flow and publish it like any other flow. Your plan may cap how many client flows you can have.
Upgrade installed flows
When you publish a newer template version, the Template column on the Flows tab shows a dot next to flows installed from an older version. On such a flow's page, a banner reads Update available with the new version, and Upgrade replaces the flow's draft with the template's current definition and checks the flow's params against the current schema.
Upgrading replaces the draft, including any saved edits made to that flow, so save or discard unsaved work first. The flow keeps running its published version until you publish again.
The clients view
The Clients tab has a card for every client with flows: their Active flows, Total flows, Runs this period, and a badge for open exceptions. View flows opens the Flows tab filtered to that client, and Install template starts an install for them. The Runs and Flows tabs also have a Client filter.
What your clients see
When the embed's flows feature is on, each client's embed session can see
their own flows and nothing else:
- Flows: the list of their flows, with a Runnable badge on the ones they may start. A flow's page lists its runs, and Run starts one with a JSON payload when you allowed it at install.
- Runs: each run's status, input, output, and step results.
- Exceptions: their failed runs, with Retry and Ignore.
- Endpoints: the endpoints of their flows. If you allow self-service keys, Create key issues the client an endpoint key for an active endpoint whose flow they can run.
Clients never see or edit flow definitions, and cannot create flows.
Enable the flows feature (and, optionally, the allowEndpointKeys setting for
self-service keys) on your embed configuration through
PATCH /api/v1/embed/config. Embed sessions then carry the
flows:read, flows:run, and flows:triage scopes.
How client isolation works
A client's flow is held to that client's data at every layer:
- Publishing refuses a client flow that uses a bridge belonging to anyone else, and exchange-document triggers cannot be used for client flows.
- At run time, steps re-check ownership: a bridge task, an order lookup, a rate shop over an operation, a label purchase, or a claim fails on any record that is not the client's. Order lookups only search the client's orders.
- In the client's portal, every list and action is filtered to the signed-in client. Another client's flow, run, or exception simply does not exist to them.
- Endpoint keys are bound to one endpoint, and a key issued for a client cannot be used on another client's endpoint.
- Runs, exceptions, and usage are tagged with the client, which is how the Client filters and the clients view are built.
Next steps
- Set up the embed: sessions, branding, and feature modules.
- Flows API: manage templates and installs programmatically.