PSA/ee/docs/plans/2026-01-25-workflow-import-export/SCRATCHPAD.md

Scratchpad — Workflow Import/Export (2026-01-25)

Context

• Workflow Runtime V2 stores:
  • workflow_definitions (draft + metadata)
  • workflow_definition_versions (published immutable versions)
• Existing test helpers exist under server/src/test/helpers/workflowRuntimeV2TestHelpers.ts.

Decisions (draft)

• Use a JSON bundle format with explicit format + formatVersion.
• V1 accepts exactly one version and rejects others (no migration/back-compat).
• “Full fidelity” targets workflow behavior + operational settings, not audit timestamps.
• Bundle requires a stable portable key per workflow (distinct from DB ids).
• Import always regenerates workflow_id.
• Import is create-only by default; --force / force=true overwrites by deleting the existing workflow (matched by key) and recreating it from the bundle.
• V1 is API-only plus a CLI wrapper in tools/ (no UI).

Proposed docs locations

• ee/docs/schemas/workflow-bundle.v1.schema.json
• ee/docs/guides/workflows/workflow-import-export.md

Open Questions to resolve

1. Do we need additional explicit validation beyond DB constraints for specific reference types (if constraints are insufficient)?

Notes / references

• Workflow Runtime V2 PRD: ee/docs/plans/2025-12-21-workflow-overhaul.md
• Persistence models:
  • shared/workflow/persistence/workflowDefinitionModelV2.ts
  • shared/workflow/persistence/workflowDefinitionVersionModelV2.ts

Work log

• 2026-01-25: Added v1 bundle header constants/types in shared/workflow/bundle/workflowBundleV1.ts (format, formatVersion, exportedAt) to centralize the accepted format/version.
• 2026-01-25: Defined v1 bundle TypeScript shape (workflow metadata + draft + published versions) in shared/workflow/bundle/workflowBundleV1.ts as the shared contract for exporter/importer/tests.
• 2026-01-25: Standardized portable workflow identifier as workflows[].key with a basic validation pattern in shared/workflow/bundle/workflowBundleV1.ts.
• 2026-01-25: Added canonical JSON rules implementation in shared/workflow/bundle/canonicalJson.ts (recursive key sort, 2-space indent, trailing newline) for stable bundle bytes.
• 2026-01-25: Added JSON Schema ee/docs/schemas/workflow-bundle.v1.schema.json (draft-07) as the machine-checkable contract for v1 bundles.
• 2026-01-25: Added human-readable format spec at ee/docs/guides/workflows/workflow-import-export.md (header, key semantics, canonical JSON, import policies).
• 2026-01-25: Added workflow_definitions.key (nullable, unique) via server/migrations/20260125120000_add_workflow_definition_key.cjs to support portable bundle identity and create/overwrite semantics. Backfills the seeded email workflow to system.email-processing.
• 2026-01-25: Implemented single-workflow exporter server/src/lib/workflow/bundle/exportWorkflowBundleV1.ts (loads workflow_definitions + workflow_definition_versions into the v1 bundle shape).
• 2026-01-25: Extended exporter to support multi-workflow bundles via exportWorkflowBundleV1ForWorkflowIds (bulk-load definitions + versions; workflows sorted by key).
• 2026-01-25: Exporter intentionally omits instance-specific audit/actor fields (timestamps, *_by, version_id) by projecting only the portable subset into the bundle.
• 2026-01-25: Exporter includes operational settings in metadata (isPaused/isVisible/concurrency/retention/auto-pause thresholds) for behavioral fidelity.
• 2026-01-25: Added dependency summary collection (shared/workflow/bundle/dependencySummaryV1.ts) and included dependencies in bundle exports (actions/node types/schema refs) to support structured missing-dependency errors on import.
• 2026-01-25: Added import-time header validation for v1 bundles in server/src/lib/workflow/bundle/validateWorkflowBundleHeaderV1.ts (rejects unsupported formatVersion with a structured error).
• 2026-01-25: Added Ajv-based bundle schema validation using ee/docs/schemas/workflow-bundle.v1.schema.json via server/src/lib/workflow/bundle/validateWorkflowBundleSchemaV1.ts.
• 2026-01-25: Added dependency validation helper server/src/lib/workflow/bundle/validateWorkflowBundleDependenciesV1.ts that checks bundle-declared actions/nodeTypes/schemaRefs against runtime registries and throws structured missing-dependency errors.
• 2026-01-25: Implemented bundle importer core in server/src/lib/workflow/bundle/importWorkflowBundleV1.ts using a single knex.transaction(...) for all writes (rolls back on any error).
• 2026-01-25: Importer creates workflow_definitions from bundle workflows (metadata + draft), regenerating workflow_id and rewriting workflow definition JSON id fields to match.
• 2026-01-25: Importer creates workflow_definition_versions for each publishedVersions[] entry, inserting immutable definition_json + payload schema snapshots.
• 2026-01-25: Importer default policy is create-only: conflicts on existing workflow_definitions.key throw WORKFLOW_KEY_CONFLICT unless force is enabled.
• 2026-01-25: Importer supports force overwrite: delete existing workflow by key (cascades versions/runs) and recreate from bundle with a regenerated workflow_id.
• 2026-01-25: Importer returns a summary object (created workflows, deleted workflows, created published versions) from importWorkflowBundleV1.
• 2026-01-25: Added HTTP export endpoint server/src/app/api/workflow-definitions/[workflowId]/export/route.ts returning canonical bundle JSON for a single workflow.
• 2026-01-25: Added HTTP import endpoint server/src/app/api/workflow-definitions/import/route.ts (POST bundle JSON; supports ?force=true; returns import summary). Updated API error handling to include structured details when present.
• 2026-01-25: Import/export endpoints are admin-gated via requireWorkflowPermission(user, 'admin', knex) in the underlying server actions.
• 2026-01-25: Added a minimal API-wrapping CLI at tools/workflow-bundle-cli/workflow-bundle.js (ESM; supports export and import with optional --cookie + --tenant headers).
• 2026-01-25: Added a representative fixture bundle server/src/test/fixtures/workflow-bundles/email-processing.v1.json (control flow + action.call usage) for import/export tests.
• 2026-01-25: Canonicalization utility shared/workflow/bundle/canonicalJson.ts is used by the export endpoint to emit stable bundle bytes and will be used in round-trip tests.
• 2026-01-25: Added integration test server/src/test/integration/workflowBundleV1.importExport.integration.test.ts covering unsupported formatVersion rejection (T001).
• 2026-01-25: Extended bundle integration tests for schema validation failures (T002).
• 2026-01-25: Added missing dependency validation coverage for actions/node types/schema refs (T003).
• 2026-01-25: Added canonical export formatting test via HTTP export route (T010).
• 2026-01-25: Added audit-field exclusion assertion for exported bundles (T011).
• 2026-01-25: Added import-to-empty-DB integration coverage (creates definitions + versions; rewrites workflow ids) (T020).
• 2026-01-25: Added create-only conflict test (duplicate key without force) (T021).
• 2026-01-25: Added force overwrite import test (delete+recreate with regenerated workflow_id) (T022).
• 2026-01-25: Added transactional rollback coverage (unique constraint failure does not persist partial workflow rows) (T023).
• 2026-01-25: Added export→import→export round-trip test with canonical normalization (exportedAt + workflowId placeholder) (T030).
• 2026-01-25: Added end-to-end execution test for imported workflows (imports bundle then runs the published version to SUCCEEDED) (T031).
• 2026-01-25: Added explicit HTTP export endpoint smoke test asserting bundle header + workflow key (T040).
• 2026-01-25: Added HTTP import endpoint test (POST bundle JSON returns summary and persists workflow row) (T041).
• 2026-01-25: Refactored tools/workflow-bundle-cli/workflow-bundle.js to expose runWorkflowBundleCli for unit testing; added CLI export test (T050).
• 2026-01-25: Added CLI import test covering --force query parameter wiring (T051).