284313f908
Some checks are pending
Bidi Control Character Guard / bidi-control-guard (push) Waiting to run
Circular Dependency Check / Check for new circular dependencies (push) Waiting to run
Citus Migration Smoke / Combined migrations on single-node Citus (push) Waiting to run
E2E Fresh Install Tests / fresh-install-e2e (push) Waiting to run
ext-v2 guardrails / Run ext-v2 guard and ESLint (push) Waiting to run
Integration Tests / Check for relevant changes (push) Waiting to run
Integration Tests / ${{ (github.event_name == 'schedule' || github.event.inputs.suite == 'full') && 'Full integration suite' || 'Tier-1 integration subset' }} (push) Blocked by required conditions
Mobile checks / Mobile lint + typecheck (push) Waiting to run
Mobile checks / Mobile unit tests (push) Waiting to run
Mobile checks / Mobile dependency audit (report) (push) Waiting to run
Mobile checks / Mobile reproducibility checks (push) Waiting to run
Secrets guard (env backups) / Ensure no tracked env backup files (push) Waiting to run
Temporal Readiness / fast-readiness (push) Waiting to run
Temporal Readiness / docker-parity (push) Waiting to run
TypeScript Type Check / Nx affected typecheck (push) Waiting to run
Unit Tests / Skipped-test budget (push) Waiting to run
Unit Tests / Nx affected unit tests (push) Waiting to run
Unit Tests / Server unit coverage (informational) (push) Waiting to run
Validate Tenant Management Schema / Check for relevant changes (push) Waiting to run
Validate Tenant Management Schema / Validate Tenant Management Schema (push) Blocked by required conditions
EE Workflows Build Guard / ee-workflows-build-guard (push) Waiting to run
Excluded: .git, node_modules, secrets/, compose.env, assemblyscript tgz Source: /opt/alga-psa on psa.joliet.tech
90 lines
7.9 KiB
Markdown
90 lines
7.9 KiB
Markdown
# 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.
|