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.

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.