Workflows

Support reference for organization-owned workflows at `/workflows`.

• Library route: `/workflows`
• Shared editor route: `/workflows/[workflow_id]?from=workflows`
• Shared runs route: `/workflows/[workflow_id]/runs?from=workflows`
• Sidebar/menu label: `Workflows`
• Legacy `/skills` and `/skills/:path*` URLs redirect to `/workflows`; they are compatibility routes, not a current Skills UI.

• Page title: `Workflows`
• Description: `Create, manage, and monitor automated workflows`
• Primary action: `Add`
• Empty state:
• title: `No workflows`
• description: `Create your first workflow to get started.`

• The page reuses the shared `useWorkflowsTable` hook with `noEmployee: true`, so it only lists workflows where `employee_id` is `null`.
• Search is server-side and is sent as `search` to `GET /api/organizations/{orgId}/workflows`. In backend code that currently filters by workflow `name`.
• Pagination is server-side.
• Date chips labeled `Added` and `Updated` are client-side only. They filter the rows already loaded on the current page; they are not sent to the backend.
• Available columns:
• `ID`
• `Name`
• `Description`
• `Added`
• `Updated`
• `ID` is hidden by default. `Added` is also hidden by default on desktop; mobile hides more columns.
• Row click opens the shared editor.
• Row actions:
• `Start Workflow`
• `Logs` -> `/workflows/{workflow_id}/runs?from=workflows`
• `Duplicate`
• `Delete`
• `Start Workflow` is disabled unless the workflow is published and the Starting Step connects to an executable step. Its disabled explanation is `Connect the Starting Step to an executable step and publish the workflow before starting it.`
• `Duplicate` is disabled while its request is in progress. Success feedback is `Workflow "{name}" duplicated`; failures show `Failed to duplicate workflow` plus the backend or fallback error.
• Bulk action:
• `Delete`
• Export is enabled.

• Selecting `Start Workflow` opens a JSON-input dialog when the published workflow has an input schema. If it has no input schema, the run starts immediately.
• While the tracked run is active, its workflow row shows `Running` and cannot be started again from that row.
• The loading notification is replaced by one terminal notification: `Workflow completed`, `Workflow failed`, or `Workflow aborted`.
• The client tracks the exact returned `run_id` and polls `GET /api/organizations/{orgId}/workflows/runs/{run_id}` every 5 seconds until the run reaches a terminal state.

• Dialog title: `New Workflow`
• Fields:
• workflow name
• AI teammate selector (offered when opened from the org library; hidden when opened from an AI teammate page)
• optional description
• Create always sends `type: structured`.
• When opened from the org library, the workflow can be attached to an AI teammate on creation or left unassigned. When opened from an AI teammate detail page, the teammate is preselected and included in the create call.
• After create succeeds, the UI redirects straight into the shared editor for that workflow.

• `/workflows` opens the same `/workflows/[workflow_id]` editor used elsewhere, with `from=workflows` for back-navigation.
• The page opens in read-only mode first.
• Header actions are currently:
• `Back to Workflows`
• `View Runs`
• `Edit`
• In edit mode:
• draft changes auto-save to `PUT /api/organizations/{orgId}/workflows/{workflow_id}/draft` after a 1 second debounce
• `Reset Draft` clears the saved draft by updating the workflow with `draft: null`
• `Publish` validates the graph and publishes `flow`, `starting_step_id`, `payload_format`, `state_definition`, `mode`, `debounce_seconds`, and `debounce_key`
• closing edit mode flushes any pending draft save and resets the canvas back to the published workflow graph

• Org workflows created from `/workflows` are structured workflows.
• The current structured builder palette exposes:
• `Run Workflow`
• `Assign AI`
• `Condition`
• `Tool`
• `Run Code`
• `User Input`
• `LLM`
• `Send Message`
• `Finish`
• grouping/support nodes such as `Starting Step` and `Group`
• The `Run Code` node editor includes `Import from Storage` and `Export to Storage` sections for declaring file transfers between organization storage and the step sandbox. Each entry pairs a storage path with a sandbox path; imports run before the code executes and exports after the code succeeds. A path can be a file or a folder, and entries support the same placeholders as the step's code.
• Backend workflow types still include `mapping` and `wait_callback`, but those node types are not in the current frontend palette and are not runnable in the processor.

• Workflow create and update paths now snapshot workflow state into the shared backend `entity_versions` store.
• Version snapshots are created through `VersionOrchestrator.handleSnapshot(...)` in `WorkflowService.create(...)` and `WorkflowService.updateModel(...)`.
• The stored entity type for workflows is `workflow`.
• Version history is backend-level support functionality confirmed in code. This doc does not claim a dedicated workflow version-history UI because that was not confirmed in the current frontend source.
• Organization-owned and teammate-assigned workflows use the same backend entity and version type: `workflow`.

• Library list:
• `GET /api/organizations/{orgId}/workflows?no_employee=true&page=<n>&limit=<n>&search=<text>`
• Create:
• `POST /api/organizations/{orgId}/workflows`
• Duplicate:
• `POST /api/organizations/{orgId}/workflows/{workflow_id}/duplicate`
• The new workflow is named `{source name} copy`, keeps the source organization/employee context and metadata, and copies `source.draft` when present or otherwise `source.flow` into the new draft.
• The copy is unpublished: its published `flow` is empty and `starting_step_id` is null until it is published.
• Employee-managed default workflows (`type: employee`) cannot be duplicated. The action is available through the Alloy AI action catalog for non-employee workflows.
• Delete and restore:
• `DELETE /api/organizations/{orgId}/workflows/{workflow_id}/`
• `POST /api/organizations/{orgId}/workflows/bulk-delete/`
• `POST /api/organizations/{orgId}/workflows/bulk-restore/`
• Shared editor:
• `GET /api/organizations/{orgId}/workflows/{workflow_id}/`
• `PUT /api/organizations/{orgId}/workflows/{workflow_id}/`
• `PUT /api/organizations/{orgId}/workflows/{workflow_id}/draft`
• `POST /api/organizations/{orgId}/workflows/{workflow_id}/publish`
• Runs surfaces:
• `GET /api/organizations/{orgId}/workflows/runs/`
• `GET /api/organizations/{orgId}/workflows/runs/{run_id}` returns one organization-scoped run plus up to 1000 step logs without requiring a workflow ID in the path
• `GET /api/organizations/{orgId}/workflows/{workflow_id}/runs/`
• `POST /api/organizations/{orgId}/workflows/{workflow_id}/runs/`
• `GET /api/organizations/{orgId}/workflows/{workflow_id}/runs/{run_id}/` keeps the stricter workflow-scoped lookup
• Version-history APIs:
• `GET /api/organizations/{orgId}/entity-versions/workflow/{workflow_id}?limit=<n>&before_version=<n>`
• `POST /api/organizations/{orgId}/entity-versions/{entity_version_id}/restore`
• Version-history API rules confirmed in backend validation:
• supported `entity_type` values are currently only `workflow` and `ai_employee`
• list `limit` defaults to `10` and maxes at `100`
• list pagination uses descending `version_number` order with `next_before_version`

• Workflow actions are organization-scoped and authorized by backend checks.