FlowSharp - flows and operational designer

Flows are the heart of FlowSharp. A Process Map shows the wider picture, but the Flow makes a process executable, phase by phase and task by task.

1. Why Flows are the heart of FlowSharp

A Flow describes how a case should move inside the organization.

Without a Flow, the process remains a described procedure. With a Flow, it becomes an operating path:

• with clear phases;
• with allowed moves;
• with assigned tasks;
• with required data;
• with advancement rules;
• with controlled automation;
• with audit and measurement.

The Flow is where FlowSharp moves from a conceptual map to real work.

2. From process to operating machine

When you design a Flow, you answer practical questions:

• where does the case start?
• which phases can it cross?
• who acts in each phase?
• which data is needed to continue?
• which checks are mandatory?
• when can automation act?
• when is human judgment required?
• when is the process complete?

This structure reduces implicit processes, hidden exceptions and untracked handoffs.

3. Visual designer

The visual designer lets you build the Flow on a canvas.

Statuses are nodes. Transitions are connections. The side panel configures phase, tasks, rules, data, AI, timeout and operational behavior.

You can create a Flow in two ways:

• manually, starting from an empty canvas;
• with AI, describing the process and refining the first draft.

AI mode accelerates the first design, but it does not replace team validation. A published Flow must always represent how the organization wants to work.

Useful tools while designing:

• Duplicate status: each status has a duplicate button that clones the phase with its tasks, rules and event subscriptions, ready to be re-connected. Individual tasks can be duplicated as well.
• {x} picker: expression-capable fields have an {x} button for guided insertion of variables and data fields, expanding nested objects and arrays too (e.g. item.data.lines[].code).
• Duplicate status names flagged: the designer warns when two statuses share the same name, avoiding ambiguity in selection menus.

4. Statuses and phases

Each status represents a meaningful phase of the process.

A status can be:

• a human work step;
• an automatic check;
• an AI evaluation;
• a waiting-for-data phase;
• a compliance checkpoint;
• an integration step;
• a final phase.

The word "phase" helps business users read the process. The word "status" clarifies that FlowSharp governs a precise path, not a free-form list of activities.

5. Transitions and allowed paths

Transitions define which moves are possible.

This is one of the most important points: in FlowSharp a case cannot go anywhere. It can only go where the Flow allows it to go.

Transitions help to:

• avoid unauthorized jumps;
• make the path clear;
• distinguish progress, rejection, return, escalation and closure;
• measure how often a case moves from one phase to another;
• keep history readable.

6. Tasks inside Flows

A task is an action that starts when an item enters a phase.

Tasks can be blocking or non-blocking. A blocking task stops the path until it is completed; a non-blocking task can run in the background.

An Auto task in Spawn mode creates a child item without implicitly copying the parent's business data. The designer can define a childData mapping, which acts as an exact allowlist, or explicitly enable full inheritance. Full inheritance raises a warning because it broadens the data sent to the child flow; _source, _taskError and the parent's provenance are never copied.

7. Rules, Data Gate and data quality

Rules decide when an item can advance automatically.

They are used to:

• evaluate amount, category, priority or risk;
• choose the next phase;
• apply controlled exceptions;
• handle timeouts or special conditions;
• avoid repetitive manual decisions.

Conditions can combine and recursively nest all, any and not groups. FlowSharp checks their shape, operators and target status both on save and on publish: a malformed rule or one targeting a disallowed phase is not published.

The Data Gate prevents the process from continuing when essential information is missing. This is especially important before AI tasks or integrations: if data is empty, incomplete or inconsistent, the Flow should stop and ask for quality, not automate badly.

8. WIP limits and work capacity

The WIP limit helps govern process capacity: how many items can be active in a flow or inside a phase before work becomes overloaded.

You can use it at two levels:

• flow level, to prevent new item creation when the process is already saturated;
• phase level, to put items in WIP waiting when that phase has reached its planned capacity.

This makes a hidden operational truth visible: a full phase should not always accept more work just because another item is ready to arrive.

In practice:

• 0 or an empty field means unlimited; the limit can also be an expression (e.g. {{flow.vars.capacity}}), making the threshold configurable without touching the flow;
• a phase can show a warning, wait, allow manual override or redirect to another phase (parking on another status, useful for overflow queues and escalation);
• items waiting in WIP stay visible, but do not start operational work until capacity is available;
• release from the queue follows priority when the flow is marked "prioritizable" (a priority data field, higher number = more important), otherwise arrival order; priority never overtakes work already admitted;
• on a phase in "manual override allowed" mode, an Admin can admit a waiting item beyond the limit by providing a mandatory (audited) reason;
• the phase timeout always wins: if a queued item reaches its timeout it moves on anyway, keeping the queue clean;
• measurements show how many cases entered WIP and how long they waited.

Each item also records its status reason — why it entered the current phase (flow start, manual move, rule, event, timeout, max iterations, WIP redirect). The reason is available to rules and scripts, and powers the badges shown in the item detail and on the board (see the "Items, tasks and human work" guide).

The WIP Gate complements the Data Gate: the Data Gate asks for better data, the WIP Gate asks for available capacity.

9. Versions and publishing

A Flow can be designed as a draft and then published.

When a published Flow is updated, a new version lets the process evolve without breaking items already in progress.

The definition and its child resources, including statuses, tasks, fields, KPIs, views, SOP links and design settings, can be changed only on a Draft version. Published, Unpublished and Disabled versions are immutable snapshots; create a new Draft version to change them.

This matters in real processes: the way of working evolves, but a case already started must remain consistent with the version it was born with.

10. Import, export and Templates

Flows can be exported and imported.

This helps to:

• reuse templates;
• move processes between environments;
• create process libraries;
• review and back up designs;
• accelerate demos and onboarding.

Import is protected against duplicates: importing the same flow twice (or creating one with a code already in use) is blocked with a clear message.

Import and template creation share a preflight aligned with the designer's contracts for codes, data paths, durations and dates, rules, roles and status references. If the core graph is invalid, no half-created Draft is left behind; optional resources that cannot be transferred are reported as warnings.

The Templates page

From the Flows section you can open the Templates page, the template library with three tabs:

• Business Model Flows: ready-made templates included with the product (e.g. Order Approval, Ticket Management), complete with sample data, tasks and rules;
• My templates: the templates saved by your organization;
• Marketplace: coming soon.

From a template you create a new draft flow with one click. Every template has a Preview button showing the flow diagram (statuses and transitions) before creating it. In the opposite direction, from an existing flow you can use "Save as template" to add it to your library.

Three ways to create a Flow

Besides the blank canvas and AI mode (see above), the "New Flow" window offers a third path: import. You can upload/paste a JSON file or paste a URL from which FlowSharp downloads the document (the download happens server-side, not from your browser). Importing from a URL requires https by default; the installation can enable local network exceptions.

Duplicate a Flow

The Duplicate button (⎘) in the Flows list creates an independent copy, always starting from the most recent version of the family: new family, version 1, Draft. Name and code get an automatic suffix ("Invoices" → "Invoices (2)"). The copy has no link back to the original: editing it does not touch the source flow, and vice versa. A FlowSharp system flow cannot be duplicated.

Importing into an existing Flow

From the Export/Import tab of a Flow's settings panel you can import a document (file, paste or URL) directly into the version you are editing, instead of creating a separate flow:

• if the version is empty (no statuses), the document replaces its content;
• if the version already has at least one status, the import creates the next Draft version of the same family, without touching the one you were working on.

Name and code always stay those of the Flow you are updating: a document with a different name does not overwrite it (a warning tells you so).

Sharing a Flow with a link

The same Export/Import tab offers Share: generates a temporary public link to this version of the Flow, so another installation can import it by pasting the URL, without exchanging a file.

• the link is valid for the time you choose (30 minutes, 2 hours, 24 hours, 7 days or a custom value) and can be used more than once until it expires;
• you can revoke it at any time from the same tab;
• the token is shown in full only at creation time: copy it right away, FlowSharp will not show it again;
• no FlowSharp access is needed to use the link: whoever receives it pastes it into the "import from URL" mode of any FlowSharp installation;
• watch what it contains: the link exposes the same complete document as an export (see What travels in an export below) — task config verbatim (webhook URLs, AI prompts), non-secret variables and assignees. Anyone who receives the link sees the Flow's full operating configuration: handle it with the same care as a URL containing credentials.

What travels in an export (and what does not)

Exporting or sharing a Flow carries the entire operating design: statuses, transitions, tasks, rules, KPIs, views, flow variables (secret values stay out, only the declaration travels), events with their full configuration, permissions and assignees (as text, to be reconciled at the destination).

Deliberately left out, because they make no sense or are not safe outside the source installation:

• designer notes (sticky notes) and the node layout on the canvas;
• task cost parameters;
• the direct link to the source installation's business entity type;
• the value of secret variables (declaration + placeholder only).

A FlowSharp system flow cannot be duplicated or updated through an import (as a blank-version replacement or as a new version); it can still be exported and shared like any other flow.

11. Good practices for designing Flows

• Start from the real path, not the ideal one.
• Keep a few clear statuses, then add detail where needed.
• Use names that business users understand.
• Distinguish manual tasks, automatic tasks and AI tasks.
• Do not automate before you know what you are measuring.
• Use clear final statuses.
• Put Data Gates where data quality is decisive.
• Publish only when the team recognizes the process as correct.

12. Flow variables and global variables

Variables let you define reusable values in one place and reference them anywhere in the flow.

There are two levels:

• Global variables: valid for the entire tenant. Managed in Management → Global Variables (requires Admin role). Referenced as {{global.vars.variableName}}.
• Flow variables: specific to a single flow. Managed in the Flow Designer panel (Variables section). Referenced as {{flow.vars.variableName}}.

Each variable has a name (key), a type (string, number, boolean, secret) and a value. Values are always stored as strings; the type controls validation on write and casting on read.

Where you can use them:

• in status Timeout (minutes) and Max iterations fields;
• in transition rule conditions and scripts;
• as the comparison value of a transition rule — e.g. item.data.amount greater than {{flow.vars.maxThreshold}}: change the threshold in one place and every rule using it adapts;
• in AI task prompts;
• in webhook and event task payloads;
• in flow-level and phase-level WIP limits;
• in embed content of forms and Do It / How To tasks;
• in any field that accepts Handlebars templates.

Practical example: if you want a status timeout to follow a configurable SLA, define a global variable slaDuration with value 48h and type the Timeout field as {{global.vars.slaDuration}}. To change the SLA for all flows, update the variable in Management.

The {x} button next to template-capable fields opens a guided insertion menu showing available global and flow variables, item fields (item.id, item.entityRefId, item.assignedTo, etc.) and data schema fields. Selecting an entry inserts the correct expression automatically (replacing any selected text). Fields containing a variable display its resolved value directly, in italics and with a dedicated color; clicking the field switches back to editing the {{...}} syntax.

Secret variables

The secret type is designed for tokens and credentials used in webhooks and AI tasks:

• the value is encrypted in the database and never shown in clear text: lists, edit forms and the {x} picker only show ••••••••;
• only an Admin can reveal the clear-text value, and every reveal is recorded in the audit log;
• in expressions it works like any other variable ({{global.vars.token}}, {{flow.vars.token}}) — in webhook headers, URLs, bodies and AI prompts; in task execution logs the value is automatically redacted;
• when editing, the value field starts empty: leaving it empty means "unchanged".

Warning: a template that writes the secret into the item data makes it visible there — that responsibility lies with whoever designs the flow.

13. Timeouts, waits and iterations

Phase timeouts and Auto task waits use the same grammar:

Valid values:

• 60 — 60 minutes, because a bare number is expressed in minutes;
• 30s, 5m, 2h, 1d, 1w — a duration with case-insensitive units;
• 1h30m — a composite duration;
• 2026-09-01T09:00:00+02:00 — an absolute ISO date;
• {{flow.vars.sla}} or {{item.data.deadline}} — a value resolved at runtime.

Durations must be positive and cannot exceed 366 days. Invalid literals are rejected on save; a past absolute date may remain in the Draft as a warning but blocks publishing. If a timeout template resolves to an invalid runtime value, the deadline is immediate (fail-closed); if this happens to a delay task, the task fails with diagnostics that do not expose the resolved value.

Max iterations remains a separate counter: it accepts a non-negative integer or an expression such as {{global.vars.maxIter}}; 0 means unlimited.

Use this capability to centralize configurable thresholds — SLAs, cycle limits, deadlines — without editing every flow each time operational policies change.

14. Case outcomes and scores

Not every closure means the same thing. On final statuses you can declare a business outcome:

• positive (OK), for example an approved order or resolved ticket;
• negative (KO), for example a rejected request or lost opportunity;
• neutral, when the process ends without a positive or negative assessment.

Each phase can also add to or subtract from an item's score. The score changes when the case enters the phase: rework can lower it, while a successful check can increase it. This lets two cases in the same status tell different stories without losing the context of their journey.

The score can also be used in progression rules. For example, a case below a threshold can be sent to a deeper review. In daily work, scores, outcomes and changes remain visible on the item, in the Monitor and in Analytics.

15. Expected path and exception routes

A real Flow is not one straight line. FlowSharp therefore lets you declare an expected path: the ordered sequence of phases that represents the intended journey. The designer highlights it in gold, and the Monitor flags cases that have moved away from it, including where the deviation occurred.

A deviation is not automatically an error: it may be a return, an escalation or a case that deserves attention. It makes out-of-standard work explicit so teams can measure and improve it. A negative final closure, for example, can be an expected outcome rather than a deviation.

Exception routes also keep timeouts, WIP and SLA handling orderly:

• you can create phases such as Escalation, Expired or Out of capacity that only the system can reach, never an operator through a manual selection;
• timeout and WIP can direct a case to a dedicated phase; the designer makes this route recognizable as an exception;
• for an SLA you can choose between a warning only and automatically moving the case to an escalation phase;
• an Administrator can still unblock an exceptional case with a forced status change, leaving an entry in its history.

Exceptions do not become invisible shortcuts: they remain part of the process, readable and measurable.

16. Flow settings and field registry

Flow settings follow one path: General, Activation, Data Schema, AI Form when manual start is enabled, Entity, Variables, KPI, Advanced and Import/Export. Activation also contains the endpoint, n8n node copy and management of API keys scoped to the Flow.

Event-based start is disabled by default on new Flows. Enable it only after deliberately choosing the events; the same tab can open event management in a new browser tab and refresh the list after a new event is created.

The Data Schema tab treats item data as a contract that can grow from real use:

• declared fields define path, type, label and the Sensitive flag;
• observed fields are recorded when they actually appear from forms, tasks, AI, n8n or APIs, together with detected type and provenance;
• an observed field can be promoted into the contract or ignored;
• conflicts between the declared type and received value remain visible with a count;
• in normal mode the value is accepted and the conflict is recorded; in strict mode, a non-conforming write is rejected across every channel.

Existing Flows initialize the registry from their available structure and data. Advanced JSON mode remains available, while the AI Form can generate its sample directly from declared fields. The Sensitive flag feeds Data Shield, masking and protected exports.

The registry governs the item payload; it does not turn operating settings into integer-only fields. In particular, slaMinutes continues to accept either a number or an expression such as {{flow.vars.sla}}; the same principle remains valid for other expression-capable settings.

17. KPIs configured on the Flow

Admins and Flow Designers find two distinct levels in the KPI tab:

• item metrics evaluate formulas over declared fields and process metrics such as age, lead time, worked minutes, cost or score;
• flow KPIs aggregate fields or item metrics with count, sum, average, minimum, maximum, standard deviation and variance, or combine other KPIs through formulas.

The editor suggests only available references, reports the exact position of errors and rejects circular dependencies. Labelled thresholds such as ok, warning and critical make the value readable on items and dashboards. If a formula uses a sensitive field, the KPI is marked as sensitive: the badge declares its origin, but the calculated value is not automatically masked.

Definitions, thresholds and goals travel with a new Flow version, keeping the operating model and its measurement system aligned.

18. Shared design and safe saves

A published Flow evolves through a new version: items already started remain bound to the version on which they began. Names and codes are unique within the organization even across differences in capitalization, whitespace or invisible characters, avoiding Flow families that look identical. A stable code uses lowercase letters, numbers, hyphens and underscores only; when omitted at creation it is derived from the name with a safe suffix if needed to avoid a collision.

If two people open the same designer, each save includes the revision from which that person started. When that revision is no longer current, FlowSharp does not overwrite the other person's work: it reports the conflict, reloads the server revision and keeps unsaved local changes available for comparison and reapplication.

The same care applies during a single save: edits made while the request is still in progress remain in the buffer and are not cleared by the server response.

19. Termination checks before publishing

FlowSharp only publishes designs with at least one genuinely reachable final state and no terminal component made entirely of non-final states. The check follows the engine's effective channels: human choice, Eval rules, timeouts, WIP redirects, iteration limits, events, and SLA escalation.

The designer displays the same codes used by the API:

• FLOW_NO_REACHABLE_FINAL: connect a final state through a route the runtime can take;
• FLOW_NONFINAL_TRAP: add an exit from the sink or cycle, or make the intended state final;
• AUTOMATION_FALLBACK_REQUIRED: configure an Eval default or a deterministic timed exit for a non-final Auto/AI state.

A drawn arrow from an automatic state is not a guarantee by itself: a rule must select it or an explicit fallback must exist.