NuklearRabbit
2afceea5e4
With explicit owner approval, traced the persistent credential-issuance rejection to a cross-transaction race in RAGcore's own dependency injection (two independent DB transactions per request instead of one shared transaction), fixed and deployed it in RAGcore, and verified a working "RAGcore Sync Token" n8n credential now exists. Unblocks workflow 3 and the RAGcoreKnowledgeProvider adapter rewrite.
95 lines
6.3 KiB
Markdown
95 lines
6.3 KiB
Markdown
# 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.
|