External System Triggers Agent

Duration: ~25 min · Level: Advanced

Prerequisites: A deployed runtime agent. HTTP client (curl, Postman) or MQTT broker access. Agent token from README-quickstart.txt.

Let ERP, MES, or custom apps start workflows on a runtime agent without going through Studio — via HTTP Event Ingress or MQTT.

Goal

POST order.received events to the agent API; the Event Router starts the correct workflow and passes the payload as trigger data.

Architecture

Your app  →  POST /api/agent/event  →  Event Router  →  Workflow Engine
              (X-Agent-Token)

Events hit the agent on the customer machine, not Studio or Cloud. See Runtime Event Ingress.

Step 1 — Configure routes at export

Open Export Runtime on an Active workflow (or bundle).
Expand External events → Customize routes & file watch.
Add an Event route:
- Source — http.
- Type — order.received (matches the JSON type field).
- Workflow — pick target workflow in bundles.
Re-export and redeploy if the agent is already installed.

Step 2 — Get the agent token

From the export ZIP:

README-quickstart.txt — agent token and dashboard port.
Or the runtime manifest (treat as secret).

HTTP requests must include header X-Agent-Token: YOUR_TOKEN.

Step 3 — Send a test event

curl -X POST "http://localhost:9090/api/agent/event" \
  -H "X-Agent-Token: YOUR_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "order.received",
    "correlationId": "erp-2026-001",
    "payload": { "orderId": "A-100", "qty": 5 }
  }'

For single-workflow exports, omit workflowId. For bundles, include "workflowId": 42.

Duplicate correlationId values return the existing run (idempotency).

Step 4 — Verify the run

Agent dashboard → recent runs.
Studio Agents tab → drill into the agent.
Downstream nodes receive payload as initial trigger data.

MQTT alternative

Configure a route with source mqtt and publish to:

nodlyn/{agentId}/event

JSON body uses the same type, workflowId, and payload fields. Secure the broker on your network.

Sample consumer (.NET)

Nodlyn publishes a reference consumer that posts events from external apps:

RuntimeIngressConsumer on GitHub — adapt for your ERP integration layer.

Swagger

After install, open http://localhost:9090/swagger on the agent host for interactive API docs (localhost only unless you configure otherwise).