MobilityOps/n8n/workflows/MANIFEST.md

n8n workflow manifest

Source of truth for the four canonical Fleet Ops n8n workflows. Definitions in this directory are cleaned exports of the live workflows on https://n8n.itworx.tech — credential values are never embedded; nodes reference named n8n credentials instead. Run n8n/workflows/check_drift.py to compare a live workflow against its repo definition.

1. Fleet Ops — Vehicle Return Orchestration

Field	Value
File	fleet-ops-vehicle-return.json
Purpose	Orchestrate the post-return follow-up (cleaning vs. attention-required) once Fleet Ops emits a vehicle.returned.v1 outbox event, and report the result back to Fleet Ops.
Trigger	Production webhook, POST /webhook/mobilityops-return, Header Auth (Fleet Ops Webhook Trigger Token)
Event contract	contracts/events.schema.json, event_type: vehicle.returned.v1 (envelope: event_id, event_type, occurred_at, correlation_id, aggregate, data)
Required credentials	Fleet Ops Webhook Trigger Token (Header Auth, on the trigger); Fleet Ops Service Token (Header Auth, on the outbound HTTP call)
Live workflow ID	mobilityops-return-processing
Active status (as of 2026-08-04)	Active / Published
Error Workflow	Fleet Ops — Workflow Error Handler (wired)
Timeouts / bounded retries	Record follow-up HTTP node: 15s timeout, retry on fail (3 tries, 1000ms wait)
Checksum (sha256)	a6f399dd77a7203dec7c0ac95e8540abf55f2703da519e06f1c37f2e1220f609

2. Fleet Ops — Scheduled Data Quality Scan

Field	Value
File	fleet-ops-data-quality-scan.json
Purpose	Periodically (and on-demand) run the Fleet Ops data-quality scan and summarize created-issue counts per rule.
Trigger	Schedule Trigger (hourly, Europe/Brussels instance timezone) + Manual Trigger for on-demand test runs
Event contract	N/A — HTTP-triggered scan call, no inbound event envelope. Request: POST /api/v1/integrations/n8n/scheduled-scan, Header Auth.
Required credentials	Fleet Ops Service Token (Header Auth, on the scan HTTP call)
Live workflow ID	mobilityops-scheduled-quality-scan
Active status (as of 2026-08-04)	Active / Published
Error Workflow	Fleet Ops — Workflow Error Handler (wired)
Timeouts / bounded retries	Run quality scan HTTP node: 15s timeout, retry on fail (3 tries, 1000ms wait)
Checksum (sha256)	c0d46e0519118e6336e35c4ea2a67edb2f14bd007909ccf9256c93733751244a

3. Fleet Ops — RAGcore Procedure Sync

Not yet built, but no longer blocked. Credential issuance for the fleet-ops application previously failed 100% of the time with an opaque rejection ("authoritative service-account state rejected issuance" via the raw API; a generic error via the admin UI). Root-caused to a genuine bug in RAGcore itself — a cross-transaction race in src/ragcore/api/v1/control/dependencies.py where get_control_application and get_credential_service each opened their own independent database transaction, so a freshly-created service account was invisible to the immediately-following credential-issue read. Fixed in RAGcore (with explicit owner approval) by sharing one request-scoped transaction between both dependencies; verified against RAGcore's own test suite (64 passing) and deployed to the live instance. A working credential now exists: n8n credential "RAGcore Sync Token" (Header Auth, Authorization: Bearer <token>), scope sources:sync for fleet-ops. Will build n8n/workflows/fleet-ops-ragcore-procedure-sync.json against the real RAGcore contract (POST /v1/uploads, GET /v1/knowledge-spaces, etc. — see contracts/ragcore-contract-assumptions.md and the live inspection notes in docs/live-ai-integration/n8n-current-state.md) next.

Field	Value
File	fleet-ops-ragcore-procedure-sync.json (not yet created)
Live workflow ID	—
Active status	Not built

4. Fleet Ops — Workflow Error Handler

Central technical workflow attached to workflows 1-2 via n8n's per-workflow "Error Workflow" setting (workflow 3 will be wired the same way once it exists). Receives n8n's standard Error Trigger payload, derives a bounded/secret-free failure report (safe error category, truncated summary, no stack trace, no headers/tokens), and POSTs it to Fleet Ops, which registers an audit event idempotently keyed on execution_id.

Field	Value
File	fleet-ops-error-handler.json
Purpose	Central error notification target for all other Fleet Ops n8n workflows
Trigger	Error Trigger (fired by n8n when an attached workflow's execution fails)
Event contract	None inbound (n8n's built-in error-trigger payload); outbound POST /api/v1/integrations/n8n/workflow-error, Header Auth, body: workflow_id, workflow_name, execution_id, failed_at, error_category (timeout|authError|connectionError|httpError|validationError|unknown), error_summary, trigger_context, correlation_id, attempt, retry_action
Required credentials	Fleet Ops Service Token (Header Auth, on the outbound HTTP call — same credential workflows 1-2 use)
Live workflow ID	Xppn2rAEqUuyiCJF
Active status (as of 2026-08-04)	Active / Published
Error Workflow (on itself)	- No Workflow - (deliberately unset — prevents a recursive error loop)
Checksum (sha256)	d9e2795b917a89a9b4a733e435661585f8011bc97f134d3643dee93ea05b0be6

Validated this round: mock-data run (Error Trigger pinned to a realistic payload) produced a real 200 {"status":"registered", ...} from the live Fleet Ops server; re-running the identical payload produced "status":"already_registered", confirming execution_id idempotency. A genuine induced failure (temporarily pointing workflow 2's HTTP node at a nonexistent path, then reverting) confirmed workflow 2 itself fails correctly against a broken endpoint and recovers cleanly once reverted; n8n's Error Workflow trigger did not fire for that manual "Execute workflow" editor run — n8n only invokes Error Workflow for unattended/production trigger executions, not manual test runs from the editor. This is a known limitation of the live-validation evidence for this round: the mock-data path exercises the same nodes/logic and the real Fleet Ops endpoint, but a fully automatic (schedule- or webhook-triggered) failure cascading into this handler was not observed live.