A machine-vibration alert that only ever reaches a dashboard is a monitoring project, not a maintenance system. The moment that actually changes outcomes is when the alert becomes a work order — assigned, tracked, closed out — without a supervisor re-keying it by hand from a screen into the ERP. That hop, alert to work order, is the flagship flow this note describes.
How the flow works
A customer’s existing shop-floor devices — PLCs, meters, VFDs — feed the Barquecon platform through @bqt/modbus-adapter, the connectivity adapter described in our companion note on Modbus integration. When a rule fires on that telemetry, the platform raises an alert and, via the createTicket action, hands it to n8n, which creates a Work Order or Issue in ERPNext, the recommended open-source ERP. This is the "IoT alert → ERP work order" flow that every one of our industry blueprints references.
Built-in dry-run mode. The n8n flow includes a DRY_RUN mode that logs the exact ERPNext payload it would post, without creating a live record — so you can validate the field mapping against your own ERPNext instance before go-live.
The architecture, device to work order
- PLC / meter / VFD registers, read over Modbus TCP or RTU (see our companion Modbus note for how we wire the transport into your rollout).
@bqt/modbus-adapterdecodes the raw registers into aTelemetryEvent:{ deviceId, ts, metrics, event? }.- Platform ingestion hands the event to the Rules engine, which evaluates a
RuleDefinition(metric, operator, threshold, sustained duration). - A rule that fires with a
createTicketaction (target: "external") is handed to the Notification/Workflow orchestrator. - The orchestrator HTTP-POSTs a small, stable JSON envelope to an n8n webhook.
- The n8n flow maps the envelope to an ERPNext doctype. In
DRY_RUN, it logs the payload and returns 200. In live mode, it POSTs to/api/resource/Work Order(or Issue) and gets back a work-order ID.
Nothing in this bundle changes the underlying telemetry contract — the alert-to-ERP hop reuses the platform’s existing createTicket rule action, so no contract edit was needed to wire it.
The trigger payload
The platform posts this envelope to the n8n webhook when a createTicket action fires. Every field derives directly from the telemetry contract:
The idempotencyKey is {tenantId}:{deviceId}:{ruleId}:{alertWindowStartMs} — stable for the life of one breach, so retried or redelivered alerts do not create duplicate work orders.
Field mapping, envelope to ERPNext
| ERPNext field (Issue) | Source |
|---|---|
subject | event.type + deviceId |
description | event.message + metrics table |
priority | event.severity — critical→Urgent, warning→High, info→Medium |
raised_by | fixed service account, e.g. iot-bot@<tenant> |
custom_device_id | deviceId |
custom_rule_id | rule.ruleId |
custom_idempotency_key | idempotencyKey — unique, the dedupe anchor |
custom_asset | resolved from deviceId via ERPNext Asset link, if provisioned |
Idempotency: no duplicate work orders
The platform may redeliver an alert at least once. Before creating a document, the flow queries ERPNext for an existing Issue with a matching custom_idempotency_key. If one is found, it returns the existing name and does nothing — idempotent success. If not found, it creates a new record. In DRY_RUN the lookup step is skipped and the payload is logged with the key, so the dedupe contract stays visible for testing.
Validating the mapping against your own n8n instance
- Import the flow definition into your n8n instance, or pilot it on ours — we run n8n self-hosted, already live and carrying other production workflows.
- Leave the
DRY_RUNflag attrueon the workflow. - POST the sample envelope above to the webhook URL.
- The flow returns
{ ok: true, dryRun: true, wouldCreate: { doctype, subject, priority, ... } }and logs the full ERPNext payload it would send — proving the mapping before you connect a live ERP.
What's built, and what we set up for your site
The payload envelope, the field mapping, and the idempotency design are fixed and documented — that's the contract every deployment uses, and n8n runs self-hosted today, already carrying other production workflows. Connecting your specific ERPNext instance — API credentials, Asset linkage, custom fields — and turning on live device telemetry from your PLCs and meters are the two pieces our engineers build for your rollout, using the same Modbus connectivity covered in our companion note.
| Piece | Status |
|---|---|
| Envelope + field mapping specification | Built in |
| n8n flow with dry-run mode | Ready to run |
| Self-hosted n8n instance | Live in production |
| Your ERPNext instance, connected | We build this for your rollout |
| Live device telemetry feeding the pipeline | We wire this during onboarding |
The seam — the exact payload shape, the field mapping, the idempotency design — is settled and testable today. Standing it up against your ERPNext instance and your device fleet is an integration project our team runs against that known contract, not an open design question.
