User Guide¶

Overview¶

Floh is a workflow engine that lets you define, execute, and monitor multi-step workflows. Workflows can include approvals, notifications, connectors to external systems, and scheduled triggers.

Roles¶

Role	Capabilities
Admin	Full system access — manage users, roles, connectors, and all workflows
Resource Manager	Create and manage workflow definitions, view reports, manage schedules
Approver	View and decide on assigned approval tasks
Requestor	Start workflows and view own request status

Dashboard¶

The dashboard shows:

Active workflow count
Total running instances
Completion rate
Pending tasks for the current user
Instance status distribution chart
Recent workflow instances

Workflows¶

Creating a Workflow¶

Navigate to Workflows and click New Workflow
Enter a name, description, and error strategy
Add steps using the step editor:
Action — execute custom logic
Approval — require one or more approvers to approve/reject
Notification — send email or in-app notification (supports internal user lookup or external email addresses)
Connector — call an external system
Transform — run a script to compute new variables from existing ones (e.g. format dates, build account names, generate UUIDs)
Condition — branch based on variable values
Click Save Draft to save
Click Publish to make the workflow available for execution

Custom Run-Start Form (Input Form Tab)¶

The Input Form tab in the workflow designer lets admins author a custom Handlebars template that controls the layout, copy, and grouping of the form shown to end-users when the workflow is started. Use this when the auto-generated field list is not enough — e.g. you need section headings, instructional copy, conditional groups, or a specific field order.

Templates are authored as HTML + Handlebars in a Monaco editor on the left; the right pane is a live, interactive preview of the end-user form that mounts real inputs as you type. Syntax errors from the Handlebars parser appear in a red strip below the editor with the offending line number when Handlebars reports one.

Below the editor, an Expansion Variables table lists every token each workflow variable exposes, grouped into four rows per variable:

{{name}} — the bare form input. Resolves to a marker span at render time and mounts a live app-dynamic-form-field at that position.
{{name.label}} — the humanized label (e.g. firstName → First Name) so you can place the label inside your own heading, caption, or layout.
{{name.description}} — the variable's description text (blank if the author hasn't set one).
{{name.default}} — the declared default value, coerced to a string.

Each row has an Insert button that drops {{token}} at the current editor caret. When {{name.label}} or {{name.description}} appear in the same block as the bare {{name}}, the renderer suppresses the dynamic field's built-in label/description so you don't see duplicates.

Authoring rules:

Reference any declared workflow variable with {{variableName}}. The token is replaced at render time by a live form control bound to that variable.
Structural Handlebars helpers ({{#if}}, {{#each}}) are evaluated against the request context (e.g. submitter info), so you can show/hide blocks dynamically.
Variables that are declared on the workflow but not referenced by the template are appended below the templated layout under "Additional fields not placed by the template" so the form always collects every required value.
Templates are sanitized server-side on save: <script>, <iframe>, inline event handlers, and javascript: URLs are stripped. Save is rejected if the Handlebars syntax does not parse.
Each template change emits a workflow.input_form_updated audit event that records added/removed variable references.
Leave the template empty to fall back to the auto-generated form.
New workflows seed the editor automatically — first from the org's default-for-type template (managed in the Template Library, see below) and otherwise from a variable-derived scaffold — so the editor is never blank. Scaffolded content is treated as "no custom form" until you edit it.
Secret variables and selfService user variables are intentionally omitted from the Expansion Variables table: secrets are set via the variable config (never on the run-start form) and selfService targets are stamped server-side from the authenticated submitter.

The right-hand preview pane uses the same renderer that end-users will see, so what you see in the designer matches what they will see in the run-start dialog.

Styling your template¶

Templates render inside the live Floh UI, so the full PrimeNG Lara theme plus the PrimeFlex 3 utility library are already loaded — you do not need to include any <style> tags or <link> stylesheets. Click the Styling reference button above the editor to open a drawer that lists every class with a short description, a live example, and a one-click copy button; or press Ctrl+Space anywhere inside a class="…" attribute to get the same catalog as Monaco autocomplete. Classes marked with ★ are the curated starting points most templates reach for.

Autocomplete understands two contexts:

Inside class="…", typing any prefix suggests PrimeFlex utility classes (grid, flex, spacing, typography, color, border, etc.). The curated entries surface first with inline documentation; the full catalog (5000+ entries including responsive variants like md:col-6 and state variants like hover:bg-primary) follows.
Inside class="pi …" on an <i>, the suggestions switch to the 300+ PrimeIcons glyph names (pi-check-circle, pi-user, pi-exclamation-triangle, etc.) — type pi- to filter.

Common starting points:

Layout: grid, col-12, col-6, md:col-6 (responsive half-width), flex, flex-column, gap-3, justify-content-between, align-items-center.
Spacing: mb-2, mt-3, p-3, py-2, px-3 (scale 0–8 where 1 = 0.25rem).
Typography: text-sm, text-lg, font-semibold, text-color-secondary (muted theme-aware copy).
Status & accent: text-red-500 (error), text-green-500 (success), text-primary (theme accent).
Panels: border-1 border-200 border-round p-3 surface-100 for a light card; shadow-2 to elevate.
Icons: always pair pi with a specific glyph — <i class="pi pi-check-circle text-green-500"></i>.

Attribute whitelist: the renderer sanitizes templates through DOMPurify's default HTML profile, which keeps class, id, style, data-*, aria-*, and standard form markup, but strips <script>, <iframe>, inline event handlers (onclick, onmouseover, etc.), and javascript: URLs. Prefer class names over inline style="" so your template keeps picking up theme colour and spacing updates automatically.

Template Library¶

Reusable input-form templates live in Templates in the sidebar. Each row carries a type (today only workflow_input_form), an optional category, a free-form tags list, and a Default for type flag. Exactly one template can be the default for a given type at a time — promoting another row demotes the previous default automatically. Templates support full CRUD plus a one-click duplicate. The seeded default starter row cannot be deleted from the UI; edit it instead, or promote a different row to default first.

Using the library from the workflow input form¶

The workflow designer's Input Form tab exposes a toolbar that wires the editor to the Template Library:

Insert from Template opens a picker with search, category, and tag filters. If the editor already has non-scaffold content, you are asked to confirm the replacement before the new content is applied. The selected template is remembered as the workflow's linked source.
Save as Template captures the current editor content as a new reusable library row (name, description, category, tags, and an optional "default for type" flag for users with template:update). The saved row automatically becomes the workflow's linked source. Requires template:create.
Sync from template (visible only when the workflow is linked) re-loads the linked template's content after a confirmation prompt — use this to pull in library changes and discard local edits. If the linked template has been deleted you get a warning toast and the link is cleared.
A Linked to: \<name> badge shows the currently linked source. The adjacent Unlink action drops the association while leaving your editor content intact, so future template updates are no longer offered.

The link is advisory — the workflow's own saved content always wins at runtime, so a stale or deleted link never breaks an existing workflow.

Email templates remain at Email Templates (/email-templates); the existing /api/email-templates API is unchanged. A future change will fold them into the unified library.

Starting a Workflow¶

Go to the workflow detail page
Click Start Instance
Provide any required input variables
The workflow begins executing steps in order

Monitoring Instances¶

Navigate to the instance detail page to see:

Current step progress (timeline view)
Step statuses
Variable values
Errors (if any)
Cancel option for running instances

Tasks¶

The My Tasks inbox shows:

Tasks tab — steps assigned to you for completion
Approvals tab — pending approval decisions

To approve or reject, click the appropriate button. Rejections prompt for comments.

Entitlements¶

Entitlements define connector-provisioned resources (e.g., group memberships, application access) that can be linked to roles.

Creating and Editing Entitlements¶

Navigate to the Entitlement Definitions page and click New Entitlement.
Enter a name and select a connector. Once a connector is selected, the provision, deprovision, and reconciliation config forms are populated with the connector's available commands.
For each config section, select a command from the dropdown and fill in the required parameters. The form shows a description of the selected command and renders input fields for each parameter.
Parameters like userId, userEmail, userDisplayName, and identityIssuer are automatically injected at runtime and displayed as informational badges -- you do not need to fill them in.
For advanced configurations or connectors without a command schema, click "Switch to JSON" to enter raw JSON directly.

Reconciliation Config¶

The reconciliation config is optional. If provided, the system periodically checks whether provisioned entitlements still exist in the target system and flags any that are missing.

Reports¶

The reports page shows:

Workflow Statistics — definition counts, instance counts, completion rates
SLA Compliance — on-time vs overdue steps
Approver Performance — decision counts per approver

Audit Log¶

The audit log records every action in the system. Filter by:

Entity type (workflow, instance, user, etc.)
Action (created, updated, approved, etc.)
Actor
Date range

Connectors¶

Google Workspace¶

For a step-by-step walkthrough of configuring the Google Workspace connector in the admin UI — including GCP prerequisites, connection fields, testing, and troubleshooting — see Configuring a Google Workspace Connector.

Connector Sync¶

For a detailed guide on syncing external systems to Floh user profiles — including match strategies, attribute mappings, and user lifecycle management — see Syncing Connectors to User Profiles.

External Identities¶

Connector-managed external accounts (Google, AD, Slack, etc.) are linked to Floh users via the user_external_identity table. For details on the data model, sync flow, and how workflows read and write identities (including the identity_link step), see External Identities.

Google Workspace Account Request Workflow¶

For a step-by-step guide to creating a self-service workflow that provisions Google Workspace accounts through the request catalog — including approval routing, account creation, and identity linking — see Google Workspace Account Request Workflow.

Google Workspace Password Reset Workflow¶

For a step-by-step guide to creating self-service, manager-approved, and "set initial password" variants of the Google Workspace password reset workflow using the connector's setPassword command — see Google Workspace Password Reset Workflow.

Administration¶

Admins can:

View and manage all users
Assign roles to users
View and test registered connectors
Create new instances of built-in connector types (e.g. a second Authifi tenant) via Connectors → New Connector → Built-in