# 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.
