Runtime Event Ingress

External systems — ERP, MES, IoT gateways, scripts, microservices — can subscribe to a deployed runtime agent and push events that start or resume workflows. This uses the agent’s Event Router, separate from Studio/Cloud APIs and separate from heartbeat monitoring.

Important: HTTP, MQTT, and file drops reach the runtime agent on the customer machine, not Studio or Nodlyn Cloud.

Architecture

HTTP  POST /api/agent/event | /data | /resume
MQTT  nodlyn/{agentId}/event | /in | /command
File  configured watch folders
        ↓
   Event Router
        ↓
   Workflow Engine

Existing workflow triggers (webhook, cron, MQTT per workflow, schedule) continue to work unchanged alongside ingress.

Configure at export

In the Export Runtime modal, expand External events → Customize routes & file watch:

Add Event routes — source http, mqtt, or file; optional type; workflow picker in bundles.
Preview: sample curl, POST events (after install), link to Swagger.
Config is saved on the workflow and included in the exported manifest.

An ingress-only workflow (Manual Start only, no cron/webhook/MQTT trigger) gets auto-generated eventRoutes unless you override them.

Authentication

HTTP requests require header X-Agent-Token — use the agent token from the export manifest or README-quickstart.txt.

If no token is configured, only localhost requests are accepted. MQTT uses broker credentials; secure the broker on your network.

HTTP — start a workflow

POST http://localhost:9090/api/agent/event
X-Agent-Token: YOUR_AGENT_TOKEN
Content-Type: application/json

{
  "type": "order.received",
  "workflowId": 42,
  "correlationId": "ext-001",
  "payload": { "orderId": "A-100" }
}

Field	Description
`workflowId`	Required in multi-workflow bundles; omit for single-workflow exports.
`type`	Matched against `eventRoutes` in the manifest.
`correlationId`	Optional idempotency key — duplicate triggers return the existing run.
`payload`	Passed into the workflow as trigger data.

Response 202: { "accepted": true, "action": "trigger", "runId": "..." }

Resume Wait For Event

POST http://localhost:9090/api/agent/resume
X-Agent-Token: YOUR_AGENT_TOKEN

{
  "eventName": "payment.received",
  "workflowId": 42,
  "payload": { "amount": 100 }
}

MQTT subscribe / publish

One MQTT client per agent. Publish JSON to topics under your agent ID (from agent-identity.json):

nodlyn/{agentId}/event — start or resume workflows.
nodlyn/{agentId}/in — alias for incoming events.
nodlyn/{agentId}/command — local operator commands (pause, resume, run, dry-run).

File watch ingress

Configure folders the agent watches; dropping a matching file triggers a workflow (no HTTP call needed). Set routes in export or appsettings.json on the agent after deploy.

Sample consumer project

Nodlyn provides a reference external consumer you can copy or run as-is:

RuntimeIngressConsumer on GitHub

The sample demonstrates all three channels:

Class	Channel
`AgentRuntimeClient.cs`	HTTP — `/api/agent/event`, `/data`, `/resume`, idempotency.
`MqttIngressPublisher.cs`	MQTT — publish to `nodlyn/{agentId}/event`, `/in`, `/command`.
`FileWatchSimulator.cs`	File — drop JSON into a watched inbox folder.

git clone https://github.com/nodlyn-dev/custom-component.git
cd custom-component/RuntimeIngressConsumer
# Edit appsettings.json — BaseUrl, AgentToken, WorkflowId
dotnet run

Interactive menu or CLI: dotnet run -- http trigger, dotnet run -- mqtt event, dotnet run -- file drop.

Approval vs event ingress (do not mix them up)

Operator approval and external event ingress are separate paths on the agent. Ingress consumers (ERP, scripts, MQTT gateways) are not blocked when a run waits for approval.

Mechanism	Direction	Port / path	Auth	Purpose
Event ingress HTTP	Inbound	Dashboard `POST /api/agent/event`	`X-Agent-Token`	Start workflow or resume Wait For Event
MQTT ingress	Inbound	Broker topics `nodlyn/{agentId}/…`	Broker + routes	Same as HTTP via MQTT
Workflow webhook trigger	Inbound	Separate `WebhookPort` (e.g. 8765)	Token per workflow trigger	Built-in Webhook trigger — unrelated to ingress API
Approval suspend alerts	Outbound	HTTPS to Teams/Slack	Incoming webhook URL	Notify ops when a run pauses — not a listener
Safety Approve / Arm	Dashboard UI	`POST /approve`, `POST /arm`	`DashboardActionToken` (or localhost)	Human sign-off for Dangerous nodes
Business approvals REST	Inbound	`POST /api/business-approvals/{id}/decide`	`X-Agent-Token`	Decide purchase/access requests — not safety gates

What still works while a run awaits approval

New triggers — HTTP/MQTT/file ingress can start other workflow runs in parallel.
Workflow webhook port — unchanged on its own listener.
Agent pause — only explicit pause (MQTT command or control plane) blocks new ingress; approval suspend does not pause the agent.

What ingress cannot do

Cannot approve or arm a Dangerous node via /api/agent/event — use the dashboard, or control-plane heartbeat commands for remote approve/arm.
Cannot resume an AwaitingApproval / AwaitingArm run with eventName — resume API only applies to AwaitingEvent (Wait For Event blocks).

Tokens at export (automatic)

Export pre-fills bin/appsettings.json:

Runtime:AgentToken — use as X-Agent-Token for ingress and business approvals API.
Runtime:DashboardActionToken — same value by default; required for remote dashboard Approve/Arm from LAN (open once with ?accessToken=).

See Approvals Explained for operator approval setup.

Swagger on the agent

After install, open http://localhost:9090/swagger on the agent machine for live API documentation and test requests.

Troubleshooting

Symptom	Check
HTTP 401	`X-Agent-Token` matches export manifest.
HTTP 404	Ingress enabled; correct `workflowId` / `eventRoutes` type.
HTTP 409 on resume	`eventName` matches Wait For Event block; run still waiting.
MQTT no run	Broker host on agent; topic base matches `agent-identity.json`.
File no run	Path exists on agent machine; filter matches file extension.