NuklearRabbit
e115031a57
The original docs described two n8n workflows but the repository only ever shipped one (return-processing); the sketched second workflow (knowledge sync) depends on RAGcore, which isn't connected here, so it stays deferred. Add POST /api/v1/integrations/n8n/scheduled-scan (X-Service-Token protected, same pattern as the return callback), calling the same run_scan() the manual "Run quality scan" UI action uses and recording a service-actor data_quality_scan_run audit event. run_scan() already only creates an issue for a condition without one open, so overlapping triggers do no duplicate domain work. n8n/mobilityops-scheduled-quality-scan.json (hourly schedule + manual test trigger, both feeding the same HTTP call) ships "active": false so it can't fire anywhere until deliberately published. Verified live against the local n8n instance via the Manual test trigger: full green execution, and the resulting data_quality_scan_run audit event (actor_type=service, actor_label="n8n scheduled scan") confirms the real round trip, not just a contract test. deploy/unraid/setup-scheduled-scan.sh mirrors the existing return-workflow publish script for the shared Unraid n8n.
2.6 KiB
n8n integration
Role
n8n orchestrates secondary cross-system work after MobilityOps commits canonical state. It is not the domain engine.
Required live workflow: return processing
Input: vehicle.returned.v1 webhook event.
Steps:
- validate event type and schema;
- derive a follow-up category from the already-calculated state;
- call the narrow MobilityOps callback endpoint with event ID and follow-up summary;
- return a stable workflow result;
- on errors, fail visibly so the outbox dispatcher can retry.
The starter export is n8n/mobilityops-return-processing.json. Claude may correct its credentials and callback route but must preserve idempotency.
Second live workflow: scheduled quality scan
RAGcore is not connected in this environment, so the originally sketched "knowledge sync" workflow below remains deferred (see "Deferred: knowledge sync"). The second implemented workflow does not depend on RAGcore or MCP Hub, so it is not blocked by them.
Input: hourly schedule trigger, or a manual trigger for on-demand testing.
Steps:
- call the narrow, service-token-protected
POST /api/v1/integrations/n8n/scheduled-scanendpoint; - the endpoint runs the same deterministic
run_scan()domain function the manual "Run quality scan" UI action uses, and records adata_quality_scan_runaudit event withactor_type=service; - return counts of newly created issues per rule type.
run_scan() only ever creates an issue for a condition that does not already have one
open, so a duplicate or overlapping trigger (a manual test run firing close to the
scheduled one, or a retried HTTP call) does no duplicate domain work.
The starter export is n8n/mobilityops-scheduled-quality-scan.json, imported and
published the same way as the return-processing workflow (see
deploy/unraid/setup-scheduled-scan.sh and docs/17-runbook.md). It ships with
"active": false so it cannot fire against any environment until deliberately
published with a real service token.
Deferred: knowledge sync
Input: manual trigger or manifest-changed event.
Steps:
- read the fixed knowledge manifest;
- call RAGcore ingestion/sync API;
- record per-document results through MobilityOps integration status API.
Deferred until RAGcore's live ingestion API is available in this environment; must not delay or block the core demo.
Outbox dispatcher
- polls pending records;
- claims with
FOR UPDATE SKIP LOCKEDor equivalent; - sends event with timeout;
- exponential backoff with a small maximum attempt count;
- supports explicit manual retry;
- preserves last error and response metadata;
- does not hold a database transaction open during network I/O.