This page documents the import and export functionality for workflows and workspaces in the Sim platform. The system supports two levels of data mobility: individual workflow serialization and complete workspace migration. Export operations serialize workflows to JSON format for sharing, version control, and backup, while import operations restore these states into the normalized database schema.
Workflows are exported and imported as JSON objects containing the complete visual and logical state. The format is strictly validated by the WorkflowStateSchema apps/sim/app/api/workflows/[id]/state/route.ts:104-113.
Each block in the blocks record follows the BlockStateSchema apps/sim/app/api/workflows/[id]/state/route.ts:51-64, which captures its position, configuration (subBlocks), and current outputs:
The WorkflowStateAPI handles the retrieval of this state via GET /api/workflows/[id]/state apps/sim/app/api/workflows/[id]/state/route.ts:120-156. It uses loadWorkflowFromNormalizedTables apps/sim/app/api/workflows/[id]/state/route.ts:138 to aggregate data from the workflow_blocks, workflow_edges, and subflow tables into a single JSON response.
Sources: apps/sim/app/api/workflows/[id]/state/route.ts:51-156, apps/sim/lib/workflows/persistence/utils.ts12-14
The platform provides multiple entry points for managing workflow data:
| Location | Action | Method | Target Entity |
|---|---|---|---|
| Workflow Canvas | Save State | PUT /api/workflows/[id]/state | workflow_blocks, workflow_edges |
| Workflow Canvas | Fetch State | GET /api/workflows/[id]/state | JSON Workflow Object |
| Workspace View | List Workflows | GET /api/workspaces | workspace & permissions |
| Copilot | Contextual Import | POST /api/copilot/chat | Workflow/Block context snippets |
When a workflow is loaded or imported, the client uses useCurrentWorkflow to interface with the WorkflowStore. This hook determines if the UI should display the live state or a historical snapshot/diff.
Import/Export UI Flow
Sources: apps/sim/app/api/workflows/[id]/state/route.ts:120-162, apps/sim/lib/workflows/persistence/utils.ts11-14
The import process involves a multi-stage pipeline that validates, sanitizes, and persists external JSON data into the system's relational schema.
Import Processing Pipeline
checkSessionOrInternalAuth apps/sim/app/api/workflows/[id]/state/route.ts:168 to ensure the requester has valid credentials.authorizeWorkflowByWorkspacePermission apps/sim/app/api/workflows/[id]/state/route.ts:178 checks for write permissions on the target workflow.sanitizeAgentToolsInBlocks apps/sim/app/api/workflows/[id]/state/route.ts:203 scans imported agent configurations to ensure referenced tools are valid and safe.saveWorkflowToNormalizedTables apps/sim/app/api/workflows/[id]/state/route.ts:231 deconstructs the JSON blob into rows for the PostgreSQL database.extractAndPersistCustomTools apps/sim/app/api/workflows/[id]/state/route.ts:238 identifies inline tool definitions within the workflow and registers them in the global workspace registry.Sources: apps/sim/app/api/workflows/[id]/state/route.ts:162-246, apps/sim/lib/workflows/persistence/utils.ts11-14
The system includes a semantic differ, computeEditSequence apps/sim/lib/workflows/training/compute-edit-sequence.ts109 which compares two CopilotWorkflowState objects. This is used during AI-driven edits to generate a list of operations (add, edit, delete, insert_into_subflow, extract_from_subflow) apps/sim/lib/workflows/training/compute-edit-sequence.ts7-21
This differ flattens nested structures using flattenBlocks apps/sim/lib/workflows/training/compute-edit-sequence.ts38 and extracts connections using extractAllEdgesFromBlocks apps/sim/lib/workflows/training/compute-edit-sequence.ts71 to identify structural changes without relying on visual coordinates.
Sources: apps/sim/lib/workflows/training/compute-edit-sequence.ts7-132
When a new workspace is created via POST /api/workspaces apps/sim/app/api/workspaces/route.ts87 the system seeds it with a default workflow using buildDefaultWorkflowArtifacts apps/sim/app/api/workspaces/route.ts186
workspace record is inserted with a unique ID and owner apps/sim/app/api/workspaces/route.ts139-148default-agent workflow is created apps/sim/app/api/workspaces/route.ts161-175saveWorkflowToNormalizedTables apps/sim/app/api/workspaces/route.ts187Sources: apps/sim/app/api/workspaces/route.ts126-219 apps/sim/lib/workflows/defaults.ts10
To support importing workflows into different workspaces or duplicating them, the system manages IDs carefully:
| Entity Type | Strategy | Reason |
|---|---|---|
| Workflow ID | New UUID | Generated during workspace initialization apps/sim/app/api/workspaces/route.ts133 or duplication. |
| Workspace ID | New UUID | Generated during POST /api/workspaces apps/sim/app/api/workspaces/route.ts132 for fresh environments. |
| Permission ID | New UUID | Created for every new workspace/user association apps/sim/app/api/workspaces/route.ts151 |
| Block IDs | Preserved | Maintained during state import to keep internal edges and loops references intact apps/sim/app/api/workflows/[id]/state/route.ts:52. |
Sources: apps/sim/app/api/workspaces/route.ts132-158 apps/sim/app/api/workflows/[id]/state/route.ts:51-64
Refresh this wiki