PSA/ee/docs/plans/2026-04-29-workflow-audit-csv-export-details/SCRATCHPAD.md

Scratchpad — Workflow Audit CSV Export Details

• Plan slug: workflow-audit-csv-export-details
• Created: 2026-04-29

What This Is

Rolling notes for improving workflow audit CSV exports so the CSV is business-readable while retaining technical references for support.

Decisions

• (2026-04-29) Use one CSV format for both business readability and support troubleshooting. Rationale: user selected option C; readable columns should be first and technical references should be retained at the end.
• (2026-04-29) Use a hybrid formatter. Known audit operations get first-class columns and summaries; unmapped safe scalar fields go into additional_details. Rationale: avoids raw JSON while preventing silent detail loss.
• (2026-04-29) Actor column should be human-readable, with actor_user_id retained as a separate trailing technical column.
• (2026-04-29) Workflow/run context should prioritize readable columns up front, with raw IDs near the end.
• (2026-04-29) JSON export remains the raw/lossless redacted export. CSV becomes the business-readable audit report.
• (2026-04-29) Do not add legacy CSV mode in v1 unless a known downstream consumer appears.

Discoveries / Constraints

• (2026-04-29) Review follow-up: real workflow audit payloads use a mix of camelCase and snake_case keys (publishedVersion, draftVersion, workflowVersion, nodePath, plus runtime action_id/step_path). Formatter aliases must support both shapes.
• (2026-04-29) Review follow-up: audit_logs stores tenant in tenant, not tenant_id; CSV enrichment should prefer authenticated tenant context and only fall back to audit_logs.tenant.
• (2026-04-29) Review follow-up: server Vitest runs from server/, so EE workflow action tests need an explicit include pattern under ../ee/packages/workflows/src/actions.
• (2026-04-29) Current CSV export in ee/packages/workflows/src/actions/workflow-runtime-v2-actions.ts only includes timestamp, operation, user_id, table_name, and record_id.
• (2026-04-29) Current export path already redacts changed_data and details via listWorkflowAuditLogsAction() before CSV/JSON serialization.
• (2026-04-29) Current export limit is EXPORT_AUDIT_LIMIT = 5000.
• (2026-04-29) Definition audit UI caller: ee/server/src/components/workflow-designer/WorkflowDefinitionAudit.tsx.
• (2026-04-29) Run audit UI caller: ee/server/src/components/workflow-designer/WorkflowRunDetails.tsx.
• (2026-04-29) API routes import exportWorkflowAuditLogsAction(), so improving that action improves route exports too.
• (2026-04-29) auditWorkflowEvent() appends actorRoles and source to details for action-written workflow audit rows.
• (2026-04-29) Runtime writeRunAudit() can produce workflow run audit rows with action_id, action_version, and step_path in details.

Commands / Runbooks

• (2026-04-29) Relevant search command used during planning:
  • rg -n "exportWorkflowAuditLogsAction|EXPORT_AUDIT_LIMIT|ListWorkflowAuditLogsInput|workflow_definition_|workflow_run_" ee/packages/workflows/src/actions ee/server/src/components/workflow-designer server/src/app/api/workflow-definitions server/src/app/api/workflow-runs packages/db/src/lib/auditLog.ts shared/workflow/runtime/actions/businessOperations/shared.ts
• (2026-04-29) Before implementation, inspect package test conventions around workflow actions and choose whether formatter helpers should be inline or separated for direct unit testing.

Links / References

• ee/packages/workflows/src/actions/workflow-runtime-v2-actions.ts
• ee/packages/workflows/src/actions/workflow-runtime-v2-schemas.ts
• ee/server/src/components/workflow-designer/WorkflowDefinitionAudit.tsx
• ee/server/src/components/workflow-designer/WorkflowRunDetails.tsx
• server/src/app/api/workflow-definitions/[workflowId]/audit/export/route.ts
• server/src/app/api/workflow-runs/[runId]/audit/export/route.ts
• packages/db/src/lib/auditLog.ts
• shared/workflow/runtime/actions/businessOperations/shared.ts

Open Questions

• Confirm exact automated test location and runner for workflow action/export helpers.
• Decide whether to keep formatter helpers in workflow-runtime-v2-actions.ts or extract to a dedicated helper module for cleaner tests.

Implementation Log

• (2026-04-29) Implemented business-readable workflow audit CSV formatter helpers in ee/packages/workflows/src/actions/workflow-audit-csv.ts.
  • Added stable CSV headers in required business-first order with trailing technical references.
  • Added known operation -> event mapping plus readable unknown-operation fallback.
  • Added flattening logic for source/workflow version/run status/reason/step path/action and changed-fields synthesis.
  • Added additional_details scalar extraction and object/array summaries (object, N items) to avoid raw JSON blobs.
  • Added actor formatting helper for full-name+email, email-only, name-only, unresolved fallback.
• (2026-04-29) Updated exportWorkflowAuditLogsAction() to use formatter helpers and enrichment while preserving default CSV contract and JSON branch behavior.
  • Preserved input parsing, export limit behavior, and filename/content-type behavior.
  • CSV branch now enriches actor display names from users and workflow/run context from workflow_definitions/workflow_runs.
  • JSON branch remains JSON.stringify(result.logs, null, 2) over redacted rows.
• (2026-04-29) Added formatter unit tests in ee/packages/workflows/src/actions/workflow-audit-csv.test.ts covering representative definition mapping, unknown fallback/additional details, CSV escaping, redaction-preservation, and actor formatting variants.

Verification Runbook

• npx vitest --root ee/packages/workflows src/actions/workflow-audit-csv.test.ts
• npx tsc -p ee/packages/workflows/tsconfig.json --noEmit

Gotchas

• WorkflowDefinitionModelV2.getById requires tenant and cannot be called with null tenant; export enrichment uses direct workflow_definitions query with optional tenant filter from audit rows.
• Definition key field is key (not workflow_key) on workflow_definitions records.
• (2026-04-29) Added test coverage for run-operation formatting (T002) and runtime action-level fields (T003) in workflow-audit-csv.test.ts.
• (2026-04-29) Implemented T008 DB-backed integration sanity coverage in server/src/test/integration/workflowAuditExport.integration.test.ts.
  • Adds real createTestDbConnection fixture setup for tenants/users/workflow_definitions/audit_logs and verifies both CSV and JSON export paths from exportWorkflowAuditLogsAction().
  • Asserts CSV returns the new business-readable header set + readable event/actor/workflow fields and JSON remains raw redacted rows (changed_data.secretRef === '***').
  • Added virtual mocks for missing workspace-only authorization modules required by workflow runtime bootstrap in this test environment.
• (2026-04-29) Added DB-availability guard in workflowAuditExport.integration.test.ts so the suite passes in environments without a reachable integration Postgres; the test executes fully when the DB connection is available.
• (2026-04-29) Implemented T009 in server/src/test/integration/workflowAuditExport.integration.test.ts.
  • Added fail-fast guard assertions for admin permission denial (403) and cross-tenant definition export access (404) to confirm existing validation remains enforced before CSV enrichment.
• (2026-04-29) Implemented T010 in server/src/test/integration/workflowAuditExport.integration.test.ts.
  • Added compatibility assertion that existing export callers can omit format and still receive default CSV output with unchanged content type and filename pattern (workflow-run-<runId>-audit.csv).
• (2026-04-29) Implemented T011 manual smoke coverage via ee/docs/plans/2026-04-29-workflow-audit-csv-export-details/T011-manual-smoke-test.md.
  • Added end-to-end admin validation steps for definition and run audit CSV exports, required column/row checks, and JSON cross-check expectations.