PSA/ee/docs/guides/workflows/workflow-import-export.md

Workflow Import/Export (Workflow Bundle v1)

This guide documents Alga PSA Workflow Runtime V2’s file-based import/export format for workflows: the workflow bundle.

Bundle file

• Filename: workflow-bundle.json (convention)
• Media type: application/json
• Canonical encoding: see Canonical JSON

Format header

Top-level required fields:

• format: must be exactly alga-psa.workflow-bundle
• formatVersion: must be exactly 1 (no automatic migration)
• exportedAt: ISO-8601 timestamp of when the bundle was generated
• workflows: array of one or more workflow entries

Stable workflow identifier (key)

Each workflow entry has a required, portable identifier:

• workflows[].key (string)
• Recommended: DNS-like names (e.g. system.email-processing)
• Expected pattern: ^[a-z0-9][a-z0-9._-]*$

This key is distinct from the database workflow_id and is the identity used for import create/upsert behavior.

Workflow entry shape

Each workflows[] entry contains:

• metadata: name/description and operational settings required for behavioral fidelity
• dependencies: derived summary of required actions/node types/schema refs
• draft: draft version number + draft workflow definition JSON
• publishedVersions: zero or more published versions (each includes definition JSON and a payload schema snapshot if present)

The machine-checkable schema lives at ee/docs/schemas/workflow-bundle.v1.schema.json.

Canonical JSON

Exports are written using canonical JSON rules to produce stable bytes suitable for diffs and round-trip tests:

• Recursively sort all object keys lexicographically
• Two-space indentation
• Trailing newline at end of file

Dependencies

workflows[].dependencies is a best-effort summary derived from included workflow definitions. Import uses this to report missing runtime registrations (actions/node types/schema refs) in a structured way.

Import semantics (v1)

Import runs all database writes in a single transaction and rolls back on any error.

Create/upsert policies:

• Create-only (default): if a workflow with the same key already exists, import fails.
• Force overwrite (opt-in): if force=true, import overwrites the existing workflow (matched by key) in place, preserving workflow_id. Published versions are replaced to match the bundle.

Fidelity scope (v1)

Import/export aims to preserve functional workflow behavior and operational settings (draft + published versions + trigger + payload schema configuration + operational flags).

Not preserved:

• Audit fields (created_at, updated_at, published_at, actor ids)
• Database ids (including version ids); workflow_id is generated when creating new workflows (and preserved when overwriting by key)